docs: encode and file_server enhancements (content negotiation) (#148)

* docs: encode: add new subdirectives

* minimum_length
* prefer
* match

* docs: file_server: add precompressed subdirectives

src/docs/markdown/caddyfile/directives/encode.md

@@ -12,13 +12,56 @@ Encodes responses using the configured encoding(s). A typical use for encoding i
 encode [<matcher>] <formats...> {
 	gzip [<level>]
 	zstd
+	minimum_length <length>
+	prefer <formats...>
+
+	# response matcher single line syntax
+	match [header <field> [<value>]] | [status <code...>]
+	# or response matcher block
+	match {
+		status <code...>
+		header <field> [<value>]
+	}
 }
 ```
 
 - **&lt;formats...&gt;** is the list of encoding formats to enable.
 - **gzip** enables Gzip compression, optionally at the specified level.
 - **zstd** enables Zstandard compression.
+- **minimum_length** the minimum number of bytes a response should have to be encoded. (Default is 512)
+- **prefer** is the ordered list of enabled encoding formats to determine, which encoding to choose if the client has no strong preference (via q-factors in the `Accept-Encoding` header).  
+  If **prefer** is not specified the first supported encoding from the `Accept-Encoding` header is used.
+- **match** is a [Response matcher](#responsematcher). Only matching Responses are encoded. The default looks like this:
 
+  ```caddy-d
+  match {
+      header Content-Type text/*
+      header Content-Type application/json*
+      header Content-Type application/javascript*
+      header Content-Type application/xhtml+xml*
+      header Content-Type application/atom+xml*
+      header Content-Type application/rss+xml*
+      header Content-Type image/svg+xml*
+  }
+  ```
+
+## Response matcher
+
+**Response matchers** can be used to filter (or classify) responses by specific criteria.
+
+### status
+
+```caddy-d
+status <code...>
+```
+
+By HTTP status code.
+
+- **&lt;code...&gt;** is a list of HTTP status codes. Special cases are `2xx`, `3xx`, ... which match against all status codes in the range of 200-299, 300-399, ... respectively
+
+### header
+
+See Request matcher [header](/docs/caddyfile/matchers#header).
 
 ## Examples
 
@@ -34,3 +77,12 @@ Enable Zstandard and Gzip compression:
 encode zstd gzip
 ```
 
+Enable Zstandard and Gzip compression and prefer Zstandard over Gzip:
+
+```caddy-d
+encode zstd gzip {
+	prefer zstd gzip
+}
+```
+
+Without the **prefer** setting, a `--compressed` HTTP request via [curl](https://curl.se/) (meaning `Accept-Encoding: deflate, gzip, br, zstd` in curl >=7.72.0) would be served with Gzip encoding, because it is the first accepted encoding that both client and server support. With the **prefer** setting Zstandard encoding is served, because the client has no preference but the server (caddy) has.

src/docs/markdown/caddyfile/directives/file_server.md

@@ -8,7 +8,6 @@ A static file server. It works by appending the request's URI path to the [site'
 
 Most often, the `file_server` directive is paired with the [`root`](/docs/caddyfile/directives/root) directive to set file root for the whole site.
 
-
 ## Syntax
 
 ```caddy-d
@@ -17,6 +16,7 @@ file_server [<matcher>] [browse] {
 	hide   <files...>
 	index  <filenames...>
 	browse [<template_file>]
+	precompressed <formats...>
 }
 ```
 
@@ -24,8 +24,9 @@ file_server [<matcher>] [browse] {
 - **root** sets the path to the site root for just this file server instance, overriding any other. Default: `{http.vars.root}` or the current working directory. Note: This subdirective only changes the root for this directive. For other directives (like [`try_files`](/docs/caddyfile/directives/try_files) or [`templates`](/docs/caddyfile/directives/templates)) to know the same site root, use the [`root`](/docs/caddyfile/directives/root) directive, not this subdirective.
 - **hide** is a list of files or folders to hide; if requested, the file server will pretend they do not exist. Accepts placeholders and glob patterns. Note that these are _file system_ paths, NOT request paths. In other words, relative paths use the current working directory as a base, NOT the site root; and all paths are transformed to their absolute form before comparisons (if possible). Specifying a file name or pattern without a path separator will hide all files with a matching name regardless of its location; otherwise, a path prefix match will be attempted, and then a globular match. Since this is a Caddyfile config, the active configuration file(s) will be added by default.
 - **index** is a list of filenames to look for as index files. Default: `index.html index.txt`
-- **<template_file>** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code <img src="/resources/images/external-link.svg">](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browsetpl.go).
+- **<template_file>** is an optional custom template file to use for directory listings. Defaults to the template that can be found [here in the source code ![external link](/resources/images/external-link.svg)](https://github.com/caddyserver/caddy/blob/master/modules/caddyhttp/fileserver/browsetpl.go).
-
+- **precompressed** is the list of encoding formats to search for precompressed sidecar files.
+- **&lt;formats...&gt;** is the ordered list of encoding formats to search for precompressed sidecar files. Supported formats are `gzip`, `zstd` and `br`.
 
 ## Examples
 
@@ -61,3 +62,11 @@ file_server {
 	hide .git
 }
 ```
+
+If supported by the client (`Accept-Encoding` header) checks the existence of precompressed files along side the requested file. So if `/path/to/file` is requested, it checks for `/path/to/file.zst`, `/path/to/file.br` and `/path/to/file.gz` in that order and serves the first available file with corresponding Content-Encoding:
+
+```caddy-d
+file_server {
+	precompressed zstd br gzip
+}
+```