From 6b4998a5dc22dc53c4024e28d26fdd160e1947df Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Thu, 12 Nov 2020 15:54:37 -0500 Subject: [PATCH] docs: Use headers for individual global options, anchor linkable (#100) --- src/docs/markdown/caddyfile/options.md | 79 +++++++++++++++++++------- src/resources/js/docs.js | 19 +++++++ 2 files changed, 76 insertions(+), 22 deletions(-) diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 2c6a0b1..e470079 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -50,25 +50,60 @@ Possible options are: } ``` -- **debug** enables debug mode, which sets all log levels to debug (unless otherwise specified). -- **http_port** is the port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: 80 -- **https_port** is the port for the server to use for HTTPS. For internal use only; does not change the HTTPS port for clients. Default: 443 -- **default_sni** sets a default TLS ServerName for when clients do not use SNI in their ClientHello. -- **order** sets or changes the standard order of HTTP handler directive(s). Can set directives to be `first` or `last`, or `before` or `after` another directive. -- **experimental_http3** enables experimental draft HTTP/3 support. Note that HTTP/3 is not a finished spec and client support is extremely limited. This option will go away in the future. _This option is not subject to compatibility promises._ -- **storage** configures Caddy's storage mechanism. Default: `file_system` -- **acme_ca** specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: Let's Encrypt's production endpoint. -- **acme_ca_root** specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store. -- **acme_eab** specifies an External Account Binding to use for all ACME transactions. -- **acme_dns** configures the DNS challenge to use for all ACME transactions. -- **email** is your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates. -- **admin** customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server. - - **origins** configures the list of remotes/origins that are allowed to connect to the endpoint. - - **enforce_origin** enables enforcement of the Origin header. (This is different from enforcing origins generally, which is always done.) -- **on_demand_tls** configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [on_demand `tls` subdirective](/docs/caddyfile/directives/tls#syntax)). Highly recommended if using in production environments, to prevent abuse. - - **ask** will cause Caddy to make an HTTP request to the given URL with a query string of `?domain=` containing the value of the domain name. If the endpoint returns 200 OK, Caddy will be authorized to obtain a certificate for that name. - - **interval** and **burst** allows `` certificate operations within `` interval. -- **local_certs** causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments. -- **key_type** specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it. -- **auto_https** configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`). See the [Automatic HTTPS](/docs/automatic-https) page for more details. -- **cert_issuer** defines the issuer (or source) of TLS certificates. +##### `debug` +Enables debug mode, which sets all log levels to debug (unless otherwise specified). + +##### `http_port` +The port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: `80` + +##### `https_port` +The port for the server to use for HTTPS. For internal use only; does not change the HTTPS port for clients. Default: `443` + +##### `default_sni` +Sets a default TLS ServerName for when clients do not use SNI in their ClientHello. + +##### `order` +Sets or changes the standard order of HTTP handler directive(s). Can set directives to be `first` or `last`, or `before` or `after` another directive. + +##### `experimental_http3` +Enables experimental draft HTTP/3 support. Note that HTTP/3 is not a finished spec and client support is extremely limited. This option will go away in the future. _This option is not subject to compatibility promises._ + +##### `storage` +Configures Caddy's storage mechanism. Default: `file_system` + +##### `acme_ca` +Specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: Let's Encrypt's production endpoint. + +##### `acme_ca_root` +Specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store. + +##### `acme_eab` +Specifies an External Account Binding to use for all ACME transactions. + +##### `acme_dns` +Configures the DNS challenge to use for all ACME transactions. + +##### `email` +Your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates. + +##### `admin` +Customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled. If disabled, config changes will be impossible without stopping and starting the server. +- **origins** configures the list of remotes/origins that are allowed to connect to the endpoint. +- **enforce_origin** enables enforcement of the Origin header. (This is different from enforcing origins generally, which is always done.) + +##### `on_demand_tls` +Configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [on_demand `tls` subdirective](/docs/caddyfile/directives/tls#syntax)). Highly recommended if using in production environments, to prevent abuse. +- **ask** will cause Caddy to make an HTTP request to the given URL with a query string of `?domain=` containing the value of the domain name. If the endpoint returns 200 OK, Caddy will be authorized to obtain a certificate for that name. +- **interval** and **burst** allows `` certificate operations within `` interval. + +##### `local_certs` +Causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments. + +##### `key_type` +Specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it. + +##### `auto_https` +Configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`). See the [Automatic HTTPS](/docs/automatic-https) page for more details. + +##### `cert_issuer` +Defines the issuer (or source) of TLS certificates. diff --git a/src/resources/js/docs.js b/src/resources/js/docs.js index d0a7b8c..a73e517 100644 --- a/src/resources/js/docs.js +++ b/src/resources/js/docs.js @@ -60,4 +60,23 @@ $(function() { .find('a') .text(text); }); + + // On the global options page only, we'll add links to the options to the anchor tags + if (window.location.pathname === '/docs/caddyfile/options') { + let headers = $('article h5').map(function (i, el) { + return el.id.replace(/-/g, "_"); + }).toArray(); + $('pre.chroma .k') + .filter(function (k, item) { + return headers.includes(item.innerText); + }) + .map(function(k, item) { + let text = item.innerText; + let url = '#' + item.innerText.replace(/_/g, "-"); + $(item) + .html('') + .find('a') + .text(text); + }); + } }); \ No newline at end of file