docs: Use headers for individual global options, anchor linkable (#100)

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).
+##### `debug`
-- **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
+Enables debug mode, which sets all log levels to debug (unless otherwise specified).
-- **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.
+##### `http_port`
-- **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.
+The port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: `80`
-- **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`
+##### `https_port`
-- **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.
+The port for the server to use for HTTPS. For internal use only; does not change the HTTPS port for clients. Default: `443`
-- **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.
+##### `default_sni`
-- **acme_dns** configures the DNS challenge to use for all ACME transactions.
+Sets a default TLS ServerName for when clients do not use SNI in their ClientHello.
-- **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.
+##### `order`
-	- **origins** configures the list of remotes/origins that are allowed to connect to the endpoint.
+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.
-	- **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.
+##### `experimental_http3`
-	- **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.
+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._
-	- **interval** and **burst** allows `<n>` certificate operations within `<duration>` 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.
+##### `storage`
-- **key_type** specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it.
+Configures Caddy's storage mechanism. Default: `file_system`
-- **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.
+##### `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 `<n>` certificate operations within `<duration>` 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.

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('<a href="' + url + '" style="color: inherit;" title="Global option"></a>')
+					.find('a')
+					.text(text);
+			});
+	}
 });