From 2e112fd9982b72a0806d820c69d60e978f21ce2e Mon Sep 17 00:00:00 2001 From: Francis Lavoie Date: Sat, 16 May 2020 09:50:13 -0400 Subject: [PATCH] docs: Add Caddyfile syntax highlighting --- src/docs/markdown/caddyfile-tutorial.md | 28 ++++---- src/docs/markdown/caddyfile.md | 2 +- src/docs/markdown/caddyfile/concepts.md | 34 +++++----- src/docs/markdown/caddyfile/directives.md | 6 +- .../caddyfile/directives/basicauth.md | 4 +- .../markdown/caddyfile/directives/bind.md | 6 +- .../markdown/caddyfile/directives/encode.md | 6 +- .../caddyfile/directives/file_server.md | 8 +-- .../markdown/caddyfile/directives/handle.md | 4 +- .../caddyfile/directives/handle_errors.md | 2 +- .../markdown/caddyfile/directives/header.md | 12 ++-- .../markdown/caddyfile/directives/import.md | 4 +- src/docs/markdown/caddyfile/directives/log.md | 32 ++++----- .../caddyfile/directives/php_fastcgi.md | 10 +-- .../markdown/caddyfile/directives/redir.md | 8 +-- .../caddyfile/directives/request_header.md | 4 +- .../markdown/caddyfile/directives/respond.md | 8 +-- .../caddyfile/directives/reverse_proxy.md | 18 ++--- .../markdown/caddyfile/directives/rewrite.md | 10 +-- .../markdown/caddyfile/directives/root.md | 8 +-- .../markdown/caddyfile/directives/route.md | 8 +-- .../caddyfile/directives/templates.md | 4 +- src/docs/markdown/caddyfile/directives/tls.md | 12 ++-- .../caddyfile/directives/try_files.md | 10 +-- src/docs/markdown/caddyfile/directives/uri.md | 8 +-- src/docs/markdown/caddyfile/matchers.md | 44 ++++++------ src/docs/markdown/caddyfile/options.md | 4 +- src/docs/markdown/command-line.md | 2 +- src/docs/markdown/getting-started.md | 2 +- src/docs/markdown/quick-starts/caddyfile.md | 6 +- src/docs/markdown/quick-starts/https.md | 2 +- .../markdown/quick-starts/reverse-proxy.md | 4 +- .../markdown/quick-starts/static-files.md | 6 +- src/docs/markdown/v2-upgrade.md | 68 ++++++++++++++----- 34 files changed, 215 insertions(+), 179 deletions(-) diff --git a/src/docs/markdown/caddyfile-tutorial.md b/src/docs/markdown/caddyfile-tutorial.md index 8d65ed39..e70bc77f 100644 --- a/src/docs/markdown/caddyfile-tutorial.md +++ b/src/docs/markdown/caddyfile-tutorial.md @@ -27,7 +27,7 @@ Create a new text file named `Caddyfile` (no extension). The first thing you should type is your site's [address](/docs/caddyfile/concepts#addresses): -``` +```caddy localhost ``` @@ -37,7 +37,7 @@ localhost Then hit enter and type what you want it to do. For this tutorial, make your Caddyfile look like this: -``` +```caddy localhost respond "Hello, world!" @@ -63,7 +63,7 @@ Open [localhost](https://localhost) in your browser and see your web server work That's not particularly exciting, so let's change our static response to a [file server](/docs/caddyfile/directives/file_server) with directory listings enabled: -``` +```caddy localhost file_server browse @@ -99,7 +99,7 @@ Page loaded at: {{`{{`}}now | date "Mon Jan 2 15:04:05 MST 2006"{{`}}`}} Wait a minute. We should see today's date. Why didn't it work? It's because the server hasn't yet been configured to evaluate templates! Easy to fix, just add a line to the Caddyfile so it looks like this: -``` +```caddy localhost templates @@ -118,7 +118,7 @@ With Caddy's [templates module](/docs/modules/http.handlers.templates), you can It's good practice to compress responses with a quick and modern compression algorithm. Let's enable Gzip and Zstandard support using the [`encode`](/docs/caddyfile/directives/encode) directive: -``` +```caddy localhost encode zstd gzip @@ -143,7 +143,7 @@ But it is easy to make it so we can add more sites! Our Caddyfile so far: -``` +```caddy localhost encode zstd gzip @@ -153,7 +153,7 @@ file_server browse is equivalent to this one: -``` +```caddy localhost { encode zstd gzip templates @@ -167,7 +167,7 @@ By wrapping our site block in curly braces `{ }` we are able to define multiple, For example: -``` +```caddy :8080 { respond "I am 8080" } @@ -181,7 +181,7 @@ When wrapping site blocks in curly braces, only [addresses](/docs/caddyfile/conc For multiple sites which share the same configuration, you can add more addresses, for example: -``` +```caddy :8080, :8081 { ... } @@ -198,7 +198,7 @@ We may want to apply some directives only to certain requests. For example, let' This config will not work like we want: -``` +```caddy localhost file_server @@ -207,7 +207,7 @@ reverse_proxy 127.0.0.1:9005 In practice, we may want to use the reverse proxy only for API requests, i.e. requests with a base path of `/api/`. This is easy to do by adding a [matcher token](/docs/caddyfile/matchers#syntax): -``` +```caddy localhost file_server @@ -232,7 +232,7 @@ First, set an environment variable (in the same shell that runs Caddy): Then you can use it like this in the Caddyfile: -``` +```caddy {$SITE_ADDRESS} file_server @@ -240,7 +240,7 @@ file_server Before the Caddyfile is parsed, it will be expanded to: -``` +```caddy localhost:9055 file_server @@ -255,7 +255,7 @@ You can use environment variables anywhere in the Caddyfile, for any number of t One last thing that you will find most helpful: if you want to remark or note anything in your Caddyfile, you can use comments, starting with `#`: -``` +```caddy # this starts a comment ``` diff --git a/src/docs/markdown/caddyfile.md b/src/docs/markdown/caddyfile.md index 68d4f4c1..19da6782 100644 --- a/src/docs/markdown/caddyfile.md +++ b/src/docs/markdown/caddyfile.md @@ -8,7 +8,7 @@ The **Caddyfile** is a convenient Caddy configuration format for humans. It is m It looks like this: -``` +```caddy example.com root * /var/www/wordpress diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index 951e7429..d63526bb 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -46,7 +46,7 @@ Opening and closing a **block** is done with curly braces: When there is only one site block, the curly braces (and indentation) are optional. This is for convenience to quickly define a single site, for example, this: -``` +```caddy localhost reverse_proxy /api/* localhost:9001 @@ -55,7 +55,7 @@ file_server is equivalent to: -``` +```caddy localhost { reverse_proxy /api/* localhost:9001 file_server @@ -66,7 +66,7 @@ when you have only a single site block; it's a matter of preference. To configure multiple sites with the same Caddyfile, you **must** use curly braces around each one to separate their configurations: -``` +```caddy example1.com { root * /www/example.com file_server @@ -84,7 +84,7 @@ If a request matches multiple site blocks, the site block with the most specific **Directives** are keywords which customize how the site is served. For example, a complete file server config might look like this: -``` +```caddy localhost file_server @@ -92,7 +92,7 @@ file_server Or a reverse proxy: -``` +```caddy localhost reverse_proxy localhost:9000 @@ -104,7 +104,7 @@ In the second example, `localhost:9000` is an **argument** because it appears on **Subdirectives** can appear in directive blocks: -``` +```caddy localhost reverse_proxy localhost:9000 localhost:9001 { @@ -121,7 +121,7 @@ The Caddyfile is lexed into tokens before being parsed. Whitespace is significan Often, directives expect a certain number of arguments; if a single argument has a value with whitespace, it would be lexed as two separate tokens: -``` +```caddy-d directive abc def ``` @@ -129,13 +129,13 @@ This could be problematic and return errors or unexpected behavior. If `abc def` is supposed to be the value of a single argument, it needs to be quoted: -``` +```caddy-d directive "abc def" ``` Quotes can be escaped if you need to use quotes in quoted tokens, too: -``` +```caddy-d directive "\"abc def\"" ``` @@ -172,13 +172,13 @@ Wildcards (`*`) may be used, but only to represent precisely one label of the ho If multiple sites share the same definition, you can list all of them together: -``` +```caddy localhost:8080, example.com, www.example.com ``` or -``` +```caddy localhost:8080, example.com, www.example.com @@ -198,7 +198,7 @@ Request matchers can be used to classify requests by a given criteria. This conc For directives that support matchers, the first argument after the directive is the **matcher token**. Here are some examples: -``` +```caddy-d root * /var/www # matcher token: * root /index.html /var/www # matcher token: /index.html root @post /var/www # matcher token: @post @@ -241,7 +241,7 @@ You can use any [Caddy placeholders](/docs/conventions#placeholders) in the Cadd You can define special blocks called snippets by giving them a name surrounded in parentheses: -``` +```caddy (redirect) { @http { scheme http @@ -252,7 +252,7 @@ You can define special blocks called snippets by giving them a name surrounded i And then you can reuse this anywhere you need: -``` +```caddy-d import redirect ``` @@ -264,7 +264,7 @@ The `import` directive can also be used to include other files in its place. As Comments start with `#` and proceed until the end of the line: -``` +```caddy-d # Comments can start a line directive # or go at the end ``` @@ -276,7 +276,7 @@ The hash character `#` cannot appear in the middle of a token (i.e. it must be p If your configuration relies on environment variables, you can use them in the Caddyfile: -``` +```caddy {$SITE_ADDRESS} ``` @@ -289,7 +289,7 @@ If you want to defer the substitution of an environment variable until runtime, A Caddyfile may optionally start with a special block that has no keys, called a [global options block](/docs/caddyfile/options): -``` +```caddy { ... } diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 9ac022a0..585e6d86 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -35,7 +35,7 @@ Directive | Description The syntax of each directive will look something like this: -``` +```caddy-d directive [] { subdirective [] } @@ -54,7 +54,7 @@ Subdirectives are always optional unless documented otherwise, even though they Most---but not all---directives accept [matcher tokens](/docs/caddyfile/matchers#syntax), which let you filter requests. Matcher tokens are usually optional. If you see this in a directive's syntax: -``` +```caddy-d [] ``` @@ -67,7 +67,7 @@ Because matcher tokens all work the same, the various possibilities for the matc Many directives manipulate the HTTP handler chain. The order in which those directives are evaluated matters, so a default ordering is hard-coded into Caddy: -``` +```caddy-d root header diff --git a/src/docs/markdown/caddyfile/directives/basicauth.md b/src/docs/markdown/caddyfile/directives/basicauth.md index 019bfcbe..6ee56cc3 100644 --- a/src/docs/markdown/caddyfile/directives/basicauth.md +++ b/src/docs/markdown/caddyfile/directives/basicauth.md @@ -15,7 +15,7 @@ Caddy configuration does not accept plaintext passwords; you MUST hash them befo ## Syntax -``` +```caddy-d basicauth [] [] { [] ... @@ -32,7 +32,7 @@ basicauth [] [] { Protect all resources in /secret so only Bob can access them with the password "hiccup": -``` +```caddy-d basicauth /secret/* { Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX } diff --git a/src/docs/markdown/caddyfile/directives/bind.md b/src/docs/markdown/caddyfile/directives/bind.md index 478c60b8..b037df02 100644 --- a/src/docs/markdown/caddyfile/directives/bind.md +++ b/src/docs/markdown/caddyfile/directives/bind.md @@ -11,7 +11,7 @@ Note that binding sites inconsistently may result in unintended consequences. Fo ## Syntax -``` +```caddy-d bind ``` @@ -22,12 +22,12 @@ bind To make a socket accessible only on the current machine, bind to the loopback interface (localhost): -``` +```caddy-d bind 127.0.0.1 ``` To include IPv6: -``` +```caddy-d bind 127.0.0.1 ::1 ``` diff --git a/src/docs/markdown/caddyfile/directives/encode.md b/src/docs/markdown/caddyfile/directives/encode.md index 94d64fa2..30b9bd89 100644 --- a/src/docs/markdown/caddyfile/directives/encode.md +++ b/src/docs/markdown/caddyfile/directives/encode.md @@ -8,7 +8,7 @@ Encodes responses using the configured encoding(s). A typical use for encoding i ## Syntax -``` +```caddy-d encode [] { gzip [] zstd @@ -24,13 +24,13 @@ encode [] { Enable Gzip compression: -``` +```caddy-d encode gzip ``` Enable Zstandard and Gzip compression: -``` +```caddy-d encode zstd gzip ``` diff --git a/src/docs/markdown/caddyfile/directives/file_server.md b/src/docs/markdown/caddyfile/directives/file_server.md index 37b246b7..7cc95ec7 100644 --- a/src/docs/markdown/caddyfile/directives/file_server.md +++ b/src/docs/markdown/caddyfile/directives/file_server.md @@ -9,7 +9,7 @@ A static file server. It works by appending the request's URI path to the [site' ## Syntax -``` +```caddy-d file_server [] [browse] { root hide @@ -29,18 +29,18 @@ file_server [] [browse] { A static file server out of the current directory: -``` +```caddy-d file_server ``` With file listings enabled: -``` +```caddy-d file_server browse ``` Only serve static files out of the `/static` folder: -``` +```caddy-d file_server /static/* ``` diff --git a/src/docs/markdown/caddyfile/directives/handle.md b/src/docs/markdown/caddyfile/directives/handle.md index 3ea8fed6..e1114ece 100644 --- a/src/docs/markdown/caddyfile/directives/handle.md +++ b/src/docs/markdown/caddyfile/directives/handle.md @@ -10,7 +10,7 @@ The `handle` directive is kind of similar to the `location` directive from nginx ## Syntax -``` +```caddy-d handle [] { } @@ -27,7 +27,7 @@ If you prefer crafting HTTP handler logic in a more inheritence-based way like n Handle requests in `/foo/` by the static file server, and send all other requests to the reverse proxy: -``` +```caddy-d handle /foo/* { file_server } diff --git a/src/docs/markdown/caddyfile/directives/handle_errors.md b/src/docs/markdown/caddyfile/directives/handle_errors.md index 8f63aab5..fc049ffe 100644 --- a/src/docs/markdown/caddyfile/directives/handle_errors.md +++ b/src/docs/markdown/caddyfile/directives/handle_errors.md @@ -10,7 +10,7 @@ When the normal HTTP request handlers return an error, normal procesing stops an ## Syntax -``` +```caddy-d handle_errors { } diff --git a/src/docs/markdown/caddyfile/directives/header.md b/src/docs/markdown/caddyfile/directives/header.md index 916fb74c..a497cf73 100644 --- a/src/docs/markdown/caddyfile/directives/header.md +++ b/src/docs/markdown/caddyfile/directives/header.md @@ -11,7 +11,7 @@ By default, header operations are performed immediately unless any of the header ## Syntax -``` +```caddy-d header [] [[+|-] [|] []] { [+] @@ -33,25 +33,25 @@ For multiple header manipulations, you can open a block and specify one manipula Set a custom header field on all requests: -``` +```caddy-d header Custom-Header "My value" ``` Strip the "Hidden" header field: -``` +```caddy-d header -Hidden ``` Replace `http://` with `https://` in any Location header: -``` +```caddy-d header Location http:// https:// ``` Set security headers on all pages: (**WARNING:** only use if you understand the implications!) -``` +```caddy-d header { # enable HSTS Strict-Transport-Security max-age=31536000; @@ -69,7 +69,7 @@ header { Multiple header directives that are intended to be mutually-exclusive: -``` +```caddy-d route { header Cache-Control max=age=3600 header /static/* Cache-Control max-age=31536000 diff --git a/src/docs/markdown/caddyfile/directives/import.md b/src/docs/markdown/caddyfile/directives/import.md index 6a42f971..956c947e 100644 --- a/src/docs/markdown/caddyfile/directives/import.md +++ b/src/docs/markdown/caddyfile/directives/import.md @@ -10,7 +10,7 @@ This directive is a special case: it is evaluated before the structure is parsed ## Syntax -``` +```caddy-d import ``` @@ -21,6 +21,6 @@ import Import all files in an adjacent sites-enabled folder: -``` +```caddy-d import sites-enabled/* ``` diff --git a/src/docs/markdown/caddyfile/directives/log.md b/src/docs/markdown/caddyfile/directives/log.md index b6cafc8c..e734a882 100644 --- a/src/docs/markdown/caddyfile/directives/log.md +++ b/src/docs/markdown/caddyfile/directives/log.md @@ -8,7 +8,7 @@ Enables and configures HTTP request logging (also known as access logs). ## Syntax -``` +```caddy-d log { output ... format ... @@ -28,7 +28,7 @@ The **output** subdirective lets you customize where logs get written. It appear Standard error (console, default). -``` +```caddy-d output stderr ``` @@ -36,7 +36,7 @@ output stderr Standard output (console). -``` +```caddy-d output stdout ``` @@ -44,7 +44,7 @@ output stdout No output. -``` +```caddy-d output discard ``` @@ -52,7 +52,7 @@ output discard A file. By default, log files are rotated ("rolled") to prevent disk space exhaustion. -``` +```caddy-d output file { roll_disabled roll_size @@ -72,7 +72,7 @@ output file { A network socket. -``` +```caddy-d output net
``` @@ -86,8 +86,8 @@ The **format** subdirective lets you customize how logs get encoded (formatted). In addition to the syntax for each individual encoder, these common properties can be set on most encoders: -``` -{ +```caddy-d +format { message_key level_key time_key @@ -114,7 +114,7 @@ In addition to the syntax for each individual encoder, these common properties c The console encoder formats the log entry for human readability while preserving some structure. -``` +```caddy-d format console ``` @@ -122,7 +122,7 @@ format console Formats each log entry as a JSON object. -``` +```caddy-d format json ``` @@ -130,7 +130,7 @@ format json Formats each log entry as [logfmt](https://brandur.org/logfmt). -``` +```caddy-d format logfmt ``` @@ -138,7 +138,7 @@ format logfmt Writes only a single field from the structure log entry. Useful if one of the fields has all the information you need. -``` +```caddy-d format single_field ``` @@ -154,13 +154,13 @@ format single_field Enable access logging (to the console): -``` +```caddy-d log ``` Write logs to a file (with log rolling, which is enabled by default): -``` +```caddy-d log { output file /var/log/access.log } @@ -168,7 +168,7 @@ log { Customize log rolling: -``` +```caddy-d log { output file /var/log/access.log { roll_size 1gb @@ -180,7 +180,7 @@ log { Use common log format (deprecated, but can be useful for older setups): -``` +```caddy-d log { format single_field common_log } diff --git a/src/docs/markdown/caddyfile/directives/php_fastcgi.md b/src/docs/markdown/caddyfile/directives/php_fastcgi.md index 26af8ad3..ef75233b 100644 --- a/src/docs/markdown/caddyfile/directives/php_fastcgi.md +++ b/src/docs/markdown/caddyfile/directives/php_fastcgi.md @@ -13,7 +13,7 @@ It expects that any `index.php` at the site root acts as a router. If that is no ## Syntax -``` +```caddy-d php_fastcgi [] ``` @@ -26,7 +26,7 @@ Since this directive is an opinionated wrapper over a reverse proxy, you can ope The `php_fastcgi` directive is the same as the following configuration: -``` +```caddy-d route { # Add trailing slash for directory requests @canonicalPath { @@ -64,18 +64,18 @@ Most modern PHP apps work well with this preset. If yours does not, feel free to Proxy all PHP requests to a FastCGI responder listening at 127.0.0.1:9000: -``` +```caddy-d php_fastcgi 127.0.0.1:9000 ``` Same, but only for requests under `/blog/`: -``` +```caddy-d php_fastcgi /blog/* 127.0.0.1:9000 ``` When using php-fpm listening via a unix socket: -``` +```caddy-d php_fastcgi unix//run/php/php7.4-fpm.sock ``` diff --git a/src/docs/markdown/caddyfile/directives/redir.md b/src/docs/markdown/caddyfile/directives/redir.md index d7cb9f1f..0ba843d6 100644 --- a/src/docs/markdown/caddyfile/directives/redir.md +++ b/src/docs/markdown/caddyfile/directives/redir.md @@ -11,7 +11,7 @@ This directive implies that a matched request is to be rejected. It is ordered v ## Syntax -``` +```caddy-d redir [] [] ``` @@ -28,18 +28,18 @@ redir [] [] Redirect all requests to `https://example.com`: -``` +```caddy-d redir https://example.com ``` Same, but preserve the existing URI: -``` +```caddy-d redir https://example.com{uri} ``` Same, but permanent: -``` +```caddy-d redir https://example.com{uri} permanent ``` \ No newline at end of file diff --git a/src/docs/markdown/caddyfile/directives/request_header.md b/src/docs/markdown/caddyfile/directives/request_header.md index 4956e501..f6beaa45 100644 --- a/src/docs/markdown/caddyfile/directives/request_header.md +++ b/src/docs/markdown/caddyfile/directives/request_header.md @@ -9,7 +9,7 @@ Manipulates HTTP header fields on the request. It can set, add, and delete heade ## Syntax -``` +```caddy-d request_header [] [[+|-] [|] []] ``` @@ -23,6 +23,6 @@ request_header [] [[+|-] [|] []] Remove the Referer header from the request: -``` +```caddy-d request_header -Referer ``` diff --git a/src/docs/markdown/caddyfile/directives/respond.md b/src/docs/markdown/caddyfile/directives/respond.md index b4205919..50a283a2 100644 --- a/src/docs/markdown/caddyfile/directives/respond.md +++ b/src/docs/markdown/caddyfile/directives/respond.md @@ -9,7 +9,7 @@ Writes a hard-coded/static response to the client. ## Syntax -``` +```caddy-d respond [] | [] { body close @@ -32,19 +32,19 @@ To clarify, the first non-matcher argument can be either a 3-digit status code o Write a 200 status with an empty body to all health checks: -``` +```caddy-d respond /health-check 200 ``` Write a simple response body to all requests: -``` +```caddy-d respond "Hello, world!" ``` Write an error response and close the connection: -``` +```caddy-d respond /secret/* "Access denied" 403 { close } diff --git a/src/docs/markdown/caddyfile/directives/reverse_proxy.md b/src/docs/markdown/caddyfile/directives/reverse_proxy.md index 470bddd4..09726a65 100644 --- a/src/docs/markdown/caddyfile/directives/reverse_proxy.md +++ b/src/docs/markdown/caddyfile/directives/reverse_proxy.md @@ -9,7 +9,7 @@ Proxies requests to one or more backends with configurable transport, load balan ## Syntax -``` +```caddy-d reverse_proxy [] [] { # backends to @@ -118,7 +118,7 @@ Caddy's proxy **transport** is pluggable: The `http` transport can look like this: -``` +```caddy-d transport http { read_buffer write_buffer @@ -146,7 +146,7 @@ transport http { The `fastcgi` transport can look like this: -``` +```caddy-d transport fastcgi { root split @@ -163,19 +163,19 @@ transport fastcgi { Reverse proxy all requests to a local backend: -``` +```caddy-d reverse_proxy localhost:9005 ``` Load-balance all requests between 3 backends: -``` +```caddy-d reverse_proxy node1:80 node2:80 node3:80 ``` Same, but only requests within `/api`, and with header affinity: -``` +```caddy-d reverse_proxy /api/* node1:80 node2:80 node3:80 { lb_policy header X-My-Header } @@ -183,7 +183,7 @@ reverse_proxy /api/* node1:80 node2:80 node3:80 { Set the upstream Host header to the address of the upstream (by default, it will retain its original, incoming value): -``` +```caddy-d reverse_proxy localhost:9000 { header_up Host {http.reverse_proxy.upstream.hostport} } @@ -191,13 +191,13 @@ reverse_proxy localhost:9000 { Reverse proxy to an HTTPS endpoint: -``` +```caddy-d reverse_proxy https://example.com ``` Strip a path prefix then proxy: -``` +```caddy-d route /prefix/* { uri strip_prefix /prefix reverse_proxy localhost:9000 diff --git a/src/docs/markdown/caddyfile/directives/rewrite.md b/src/docs/markdown/caddyfile/directives/rewrite.md index 96529673..d113c91c 100644 --- a/src/docs/markdown/caddyfile/directives/rewrite.md +++ b/src/docs/markdown/caddyfile/directives/rewrite.md @@ -13,7 +13,7 @@ Because `rewrite` essentially performs an internal redirect, the Caddyfile adapt ## Syntax -``` +```caddy-d rewrite [] ``` @@ -24,25 +24,25 @@ rewrite [] Rewrite all requests to `foo.html`, leaving any query string unchanged: -``` +```caddy-d rewrite * /foo.html ``` Replace the query string on API requests with `a=b`, leaving the path unchanged: -``` +```caddy-d rewrite /api/* ?a=b ``` Preserve the existing query string and add a key-value pair: -``` +```caddy-d rewrite /api/* ?{query}&a=b ``` Change both the path and query string, preserving the original query string while adding the original path as the `p` parameter: -``` +```caddy-d rewrite * /index.php?{query}&p={path} ``` diff --git a/src/docs/markdown/caddyfile/directives/root.md b/src/docs/markdown/caddyfile/directives/root.md index 7b769be2..62b6c112 100644 --- a/src/docs/markdown/caddyfile/directives/root.md +++ b/src/docs/markdown/caddyfile/directives/root.md @@ -11,7 +11,7 @@ Specifically, this directive sets the `{http.vars.root}` placeholder. It is mutu ## Syntax -``` +```caddy-d root [] ``` @@ -23,7 +23,7 @@ Note that a matcher token is usually required since the first argument is a path Set the site root to `/home/user/public_html` for all requests: -``` +```caddy-d root * /home/user/public_html ``` @@ -31,7 +31,7 @@ root * /home/user/public_html Set the site root to `public_html` (relative to current working directory) for all requests: -``` +```caddy-d root public_html ``` @@ -39,6 +39,6 @@ root public_html Set the site root only for requests in `/foo`: -``` +```caddy-d root /foo/* /home/user/public_html/foo ``` diff --git a/src/docs/markdown/caddyfile/directives/route.md b/src/docs/markdown/caddyfile/directives/route.md index 44dee21c..f5fe6a0f 100644 --- a/src/docs/markdown/caddyfile/directives/route.md +++ b/src/docs/markdown/caddyfile/directives/route.md @@ -13,7 +13,7 @@ This directive is a special case in that its subdirectives are also regular dire ## Syntax -``` +```caddy-d route [] { } @@ -37,7 +37,7 @@ However, there may be occasions where the second directive (`redir`) has a more So you might try a Caddyfile like this (but this will not work as expected!): -``` +```caddy example.com file_server /specific.html @@ -48,7 +48,7 @@ The problem is that, internally, `redir` comes before `file_server`, but in this Fortunately, the solution is easy: just wrap those two directives in a `route` block: -``` +```caddy example.com route { @@ -68,7 +68,7 @@ And now `file_server` will be chained in before `redir` because the order is tak Strip `/api` prefix from request path just before proxying all API requests to a backend: -``` +```caddy-d route /api/* { uri strip_prefix /api reverse_proxy localhost:9000 diff --git a/src/docs/markdown/caddyfile/directives/templates.md b/src/docs/markdown/caddyfile/directives/templates.md index 3049d1f0..a1fefbd0 100644 --- a/src/docs/markdown/caddyfile/directives/templates.md +++ b/src/docs/markdown/caddyfile/directives/templates.md @@ -9,7 +9,7 @@ Executes the response body as a [template](/docs/modules/http.handlers.templates ## Syntax -``` +```caddy-d templates [] { mime between @@ -26,7 +26,7 @@ templates [] { Enable templates on all requests: -``` +```caddy-d templates ``` diff --git a/src/docs/markdown/caddyfile/directives/tls.md b/src/docs/markdown/caddyfile/directives/tls.md index 9d020c84..7ca23434 100644 --- a/src/docs/markdown/caddyfile/directives/tls.md +++ b/src/docs/markdown/caddyfile/directives/tls.md @@ -13,7 +13,7 @@ Compatibility note: Due to its sensitive nature as a security protocol, delibera ## Syntax -``` +```caddy-d tls [internal|] | [ ] { protocols [] ciphers @@ -69,19 +69,19 @@ tls [internal|] | [ ] { Use a custom certificate and key: -``` +```caddy-d tls cert.pem key.pem ``` Use locally-trusted certificates for all hosts on the current site block, rather than public certificates via ACME / Let's Encrypt (useful in dev environments): -``` +```caddy-d tls internal ``` Use locally-trusted certificates, but managed on-demand intead of in the background: -``` +```caddy-d tls internal { on_demand } @@ -89,13 +89,13 @@ tls internal { Specify an email address for your ACME account (but if only one email is used for all sites, we recommend the `email` [global option](/docs/caddyfile/options) instead): -``` +```caddy-d tls your@email.com ``` Enable the DNS challenge for a domain managed on Cloudflare with account credentials in an environment variable: -``` +```caddy-d tls { dns cloudflare {env.CLOUDFLARE_API_TOKEN} } diff --git a/src/docs/markdown/caddyfile/directives/try_files.md b/src/docs/markdown/caddyfile/directives/try_files.md index afe4631b..000c70a1 100644 --- a/src/docs/markdown/caddyfile/directives/try_files.md +++ b/src/docs/markdown/caddyfile/directives/try_files.md @@ -9,7 +9,7 @@ Rewrites the request URI path to the first of the listed files which exists in t ## Syntax -``` +```caddy-d try_files ``` @@ -20,7 +20,7 @@ try_files The `try_files` directive is basically a shortcut for: -``` +```caddy-d @try_files { file { try_files @@ -36,18 +36,18 @@ Note that this directive does not accept a matcher token. If you need more compl If the request does not match any static files, rewrite to an index/router file: -``` +```caddy-d try_files {path} /index.php ``` Same, but adding the original path to the query string: -``` +```caddy-d try_files {path} /index.php?{query}&p={path} ``` Same, but also match directories: -``` +```caddy-d try_files {path} {path}/ /index.php?{query}&p={path} ``` diff --git a/src/docs/markdown/caddyfile/directives/uri.md b/src/docs/markdown/caddyfile/directives/uri.md index 3b8b617a..71ae1166 100644 --- a/src/docs/markdown/caddyfile/directives/uri.md +++ b/src/docs/markdown/caddyfile/directives/uri.md @@ -11,7 +11,7 @@ This directive is distinct from [`rewrite`](rewrite) in that `uri` _partially_ c ## Syntax -``` +```caddy-d uri [] strip_prefix|strip_suffix|replace \ \ [ []] @@ -30,18 +30,18 @@ uri [] strip_prefix|strip_suffix|replace \ Strip `/api` from the beginning of all request paths: -``` +```caddy-d uri strip_prefix /api ``` Strip `.php` from the end of all request paths: -``` +```caddy-d uri strip_suffix .php ``` Replace "/docs/" with "/v1/docs/" in any request URI: -``` +```caddy-d uri replace /docs/ /v1/docs/ ``` diff --git a/src/docs/markdown/caddyfile/matchers.md b/src/docs/markdown/caddyfile/matchers.md index 635f2627..92d8475f 100644 --- a/src/docs/markdown/caddyfile/matchers.md +++ b/src/docs/markdown/caddyfile/matchers.md @@ -31,25 +31,25 @@ Matcher tokens are [usually optional](/docs/caddyfile/directives#matchers). If a This directive applies to [all](#wildcard-matchers) HTTP requests: -``` +```caddy-d reverse_proxy localhost:9000 ``` And this is the same: -``` +```caddy-d reverse_proxy * localhost:9000 ``` But this directive applies only to requests having a [path](#path-matchers) starting with `/api/`: -``` +```caddy-d reverse_proxy /api/* localhost:9000 ``` To match on anything other than a path, define a [named matcher](#named-matchers) and refer to it using `@name`: -``` +```caddy-d @post { method POST } @@ -63,7 +63,7 @@ reverse_proxy @post localhost:9000 The wildcard matcher `*` matches all requests, and is only needed if a matcher token is required. For example, if the first argument you want to give a directive also happens to be a path, it would look exactly like a path matcher! So you can use a wildcard matcher to disambiguate, for example: -``` +```caddy-d root * /home/www/mysite ``` @@ -74,7 +74,7 @@ Otherwise, this matcher is not often used. It is convenient to omit it when poss Because matching by path is so common, a single path matcher can be inlined, like so: -``` +```caddy-d redir /old.html /new.html ``` @@ -87,7 +87,7 @@ Path matcher tokens must start with a forward slash `/`. Defining a matcher with a unique name gives you more flexibility, allowing you to combine [any available matchers](#standard-matchers) into a set: -``` +```caddy-d @name { ... } @@ -97,7 +97,7 @@ Then you can use the matcher like so: `@name` For example: -``` +```caddy-d @websockets { header Connection *Upgrade* header Upgrade websocket @@ -140,7 +140,7 @@ Full matcher documentation can be found [in each respective matcher module's doc ⚠️ _This module is still experimental and, as such, may experience breaking changes._ -``` +```caddy-d expression ``` @@ -150,14 +150,14 @@ As a special case, Caddy [placeholders](/docs/conventions#placeholders) (or [Cad Examples: -``` +```caddy-d expression {method}.startsWith("P") ``` ### file -``` +```caddy-d file { root try_files @@ -182,7 +182,7 @@ An empty `file` matcher will see if the requested file (verbatim from the URI, r ### header -``` +```caddy-d header ``` @@ -198,7 +198,7 @@ By request header fields. ### header_regexp -``` +```caddy-d header_regexp [] ``` @@ -207,7 +207,7 @@ Like `header`, but supports regular expressions. Capture groups can be accessed ### host -``` +```caddy-d host ``` @@ -216,7 +216,7 @@ Matches request by the `Host` header field of the request. It is not common to u ### method -``` +```caddy-d method ``` @@ -225,13 +225,13 @@ By the method (verb) of the HTTP request. Verbs should be uppercase, like `POST` ### not -``` +```caddy-d not ``` or, to negate multiple matchers which get AND'ed, open a block: -``` +```caddy-d not { } @@ -242,7 +242,7 @@ The results of the enclosed matchers will be negated. ### path -``` +```caddy-d path ``` @@ -256,7 +256,7 @@ By request path, meaning the path component of the request's URI. Path matches a ### path_regexp -``` +```caddy-d path_regexp [] ``` @@ -265,7 +265,7 @@ Like `path`, but supports regular expressions. Capture groups can be accessed vi ### protocol -``` +```caddy-d protocol http|https|grpc ``` @@ -274,7 +274,7 @@ By request protocol. ### query -``` +```caddy-d query =... ``` @@ -283,7 +283,7 @@ By query string parameters. Should be a sequence of `key=value` pairs. Keys are ### remote_ip -``` +```caddy-d remote_ip ``` diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md index 2f3583dd..388a48b2 100644 --- a/src/docs/markdown/caddyfile/options.md +++ b/src/docs/markdown/caddyfile/options.md @@ -8,7 +8,7 @@ The Caddyfile has a way for you to specify options that apply globally. Some opt The very top of your Caddyfile can be a **global options block**. This is a block that has no keys: -``` +```caddy { ... } @@ -18,7 +18,7 @@ There can only be one at most, and it must be the first block of the Caddyfile. Possible options are: -``` +```caddy { debug http_port diff --git a/src/docs/markdown/command-line.md b/src/docs/markdown/command-line.md index d2cfd3cb..a932f8cf 100644 --- a/src/docs/markdown/command-line.md +++ b/src/docs/markdown/command-line.md @@ -93,7 +93,7 @@ Adapts a configuration to Caddy's native JSON config structure and writes the ou Note that a config which is successfully adapted may still fail validation. For an example of this, use this Caddyfile: -``` +```caddy localhost tls cert_notexist.pem key_notexist.pem diff --git a/src/docs/markdown/getting-started.md b/src/docs/markdown/getting-started.md index 565c571b..0c62442a 100644 --- a/src/docs/markdown/getting-started.md +++ b/src/docs/markdown/getting-started.md @@ -112,7 +112,7 @@ That was _kind of a lot of work_ just for Hello World. Another way to configure Caddy is with the [**Caddyfile**](/docs/caddyfile). The same config we wrote in JSON above can be expressed simply as: -``` +```caddy :2015 respond "Hello, world!" diff --git a/src/docs/markdown/quick-starts/caddyfile.md b/src/docs/markdown/quick-starts/caddyfile.md index 7597b1a8..0c498f12 100644 --- a/src/docs/markdown/quick-starts/caddyfile.md +++ b/src/docs/markdown/quick-starts/caddyfile.md @@ -8,7 +8,7 @@ Create a new text file named `Caddyfile` (no extension). The first thing to type in a Caddyfile is your site's address: -``` +```caddy localhost ``` @@ -18,7 +18,7 @@ localhost Then hit enter and type what you want it to do, so it looks like this: -``` +```caddy localhost respond "Hello, world!" @@ -43,7 +43,7 @@ Hello, world! You can define multiple sites in a Caddyfile by wrapping them in curly braces `{ }`. Change your Caddyfile to be: -``` +```caddy localhost { respond "Hello, world!" } diff --git a/src/docs/markdown/quick-starts/https.md b/src/docs/markdown/quick-starts/https.md index bf5521e0..7b33d4e2 100644 --- a/src/docs/markdown/quick-starts/https.md +++ b/src/docs/markdown/quick-starts/https.md @@ -40,7 +40,7 @@ This is the most common way to get HTTPS. Create a file called `Caddyfile` (no extension) where the first line is your domain name, for example: -``` +```caddy example.com respond "Hello, privacy!" diff --git a/src/docs/markdown/quick-starts/reverse-proxy.md b/src/docs/markdown/quick-starts/reverse-proxy.md index f1e776ff..965a22fc 100644 --- a/src/docs/markdown/quick-starts/reverse-proxy.md +++ b/src/docs/markdown/quick-starts/reverse-proxy.md @@ -36,7 +36,7 @@ Then make a request to [localhost](https://localhost) (or whatever address you s In the current working directory, create a file called `Caddyfile` with these contents: -``` +```caddy localhost reverse_proxy 127.0.0.1:9000 @@ -50,7 +50,7 @@ You can then make a request to [https://localhost](https://localhost) to see it It's easy to change the proxy's address: -``` +```caddy :2016 reverse_proxy 127.0.0.1:9000 diff --git a/src/docs/markdown/quick-starts/static-files.md b/src/docs/markdown/quick-starts/static-files.md index 65c9a769..e9779025 100644 --- a/src/docs/markdown/quick-starts/static-files.md +++ b/src/docs/markdown/quick-starts/static-files.md @@ -41,7 +41,7 @@ You can use another folder as the site root: In the root of your site, create a file called `Caddyfile` with these contents: -``` +```caddy localhost file_server @@ -59,7 +59,7 @@ The [`file_server` directive](/docs/caddyfile/directives/file_server) has more o If you don't have an index file but you want to display a file listing, use the `browse` argument: -``` +```caddy localhost file_server browse @@ -67,7 +67,7 @@ file_server browse You can also use another folder as the site root: -``` +```caddy localhost root * /home/me/mysite diff --git a/src/docs/markdown/v2-upgrade.md b/src/docs/markdown/v2-upgrade.md index 63dab483..86c44d9b 100644 --- a/src/docs/markdown/v2-upgrade.md +++ b/src/docs/markdown/v2-upgrade.md @@ -126,7 +126,7 @@ basicauth /secret/ Bob hiccup ``` - **v2:** -``` +```caddy-d basicauth /secret/* { Bob JDJhJDEwJEVCNmdaNEg2Ti5iejRMYkF3MFZhZ3VtV3E1SzBWZEZ5Q3VWc0tzOEJwZE9TaFlZdEVkZDhX } @@ -137,8 +137,14 @@ basicauth /secret/* { File browsing is now enabled through the [`file_server`](/docs/caddyfile/directives/file_server) directive. -- **v1:** `browse /subfolder/` -- **v2:** `file_server /subfolder/* browse` +- **v1:** +``` +browse /subfolder/ +``` +- **v2:** +```caddy-d +file_server /subfolder/* browse +``` ### ext @@ -153,8 +159,14 @@ Implied file extensions can be done with [`try_files`](/docs/caddyfile/directive Assuming you're serving PHP, the v2 equivalent is [`php_fastcgi`](/docs/caddyfile/directives/php_fastcgi). -- **v1:** `fastcgi / localhost:9005 php` -- **v2:** `php_fastcgi localhost:9005` +- **v1:** +``` +fastcgi / localhost:9005 php +``` +- **v2:** +```caddy-d +php_fastcgi localhost:9005 +``` Note that the `fastcgi` directive from v1 did a lot under the hood, including trying files on disk, rewriting requests, and even redirecting. The v2 `php_fastcgi` directive also does these things for you, but the docs give its [expanded form](/docs/caddyfile/directives/php_fastcgi#expanded-form) that you can modify if your requirements are different. @@ -167,8 +179,14 @@ The subdirectives are different in v2 -- you probably will not need any for PHP. A single directive [`encode`](/docs/caddyfile/directives/encode) is now used for all response encodings, including multiple compression formats. -- **v1:** `gzip` -- **v2:** `encode gzip` +- **v1:** +``` +gzip +``` +- **v2:** +```caddy-d +encode gzip +``` Fun fact: Caddy 2 also supports `zstd` (but no browsers do yet). @@ -177,8 +195,14 @@ Fun fact: Caddy 2 also supports `zstd` (but no browsers do yet). [Mostly unchanged](/docs/caddyfile/directives/header), but now way more powerful since it can do substring replacements in v2. -- **v1:** `header / Strict-Transport-Security max-age=31536000;` -- **v2:** `header Strict-Transport-Security max-age=31536000;` +- **v1:** +``` +header / Strict-Transport-Security max-age=31536000; +``` +- **v2:** +```caddy-d +header Strict-Transport-Security max-age=31536000; +``` ### log @@ -187,7 +211,7 @@ Enables access logging; the [`log`](/docs/caddyfile/directives/log) directive ca The recommended way to enable access logging is simply: -``` +```caddy-d log ``` @@ -201,7 +225,7 @@ log access.log ``` - **v2:** -``` +```caddy-d log { output file access.log format single_field common_log @@ -223,8 +247,14 @@ Websocket proxying "just works" in v2; there is no need to "enable" websockets l The `without` subdirective has been removed because [rewrite hacks](#rewrite) are no longer necessary in v2 thanks to improved matcher support. -- **v1:** `proxy / localhost:9005` -- **v2:** `reverse_proxy localhost:9005` +- **v1:** +``` +proxy / localhost:9005 +``` +- **v2:** +```caddy-d +reverse_proxy localhost:9005 +``` ### redir @@ -249,7 +279,7 @@ rewrite { } ``` - **v2:** -``` +```caddy-d @mobile { header User-Agent *mobile* } @@ -277,8 +307,14 @@ Because it accepts a matcher in v2, this means you can also change the site root The v2 equivalent is [`respond`](/docs/caddyfile/directives/respond), which can also write a response body. -- **v1:** `status 404 /secrets/` -- **v2:** `respond /secrets/* 404` +- **v1:** +``` +status 404 /secrets/ +``` +- **v2:** +```caddy-d +respond /secrets/* 404 +``` ### templates