From f74f5ade03ab4f4b99cbfbb6a689de2cd52bfbfb Mon Sep 17 00:00:00 2001 From: Matthew Holt Date: Tue, 11 Feb 2020 11:48:18 -0700 Subject: [PATCH] Clarify a few things --- src/docs/markdown/api.md | 2 ++ src/docs/markdown/caddyfile-tutorial.md | 2 +- src/docs/markdown/caddyfile.md | 3 ++- src/docs/markdown/caddyfile/concepts.md | 12 +++++++----- src/docs/markdown/extending-caddy.md | 2 +- 5 files changed, 13 insertions(+), 8 deletions(-) diff --git a/src/docs/markdown/api.md b/src/docs/markdown/api.md index 1c3e338..f6b15b6 100644 --- a/src/docs/markdown/api.md +++ b/src/docs/markdown/api.md @@ -10,6 +10,8 @@ Caddy is configured through an administration endpoint which can be accessed via The latest configuration will be saved to disk after any changes (unless [disabled](/docs/json/admin/config/)). You can resume the last working config after a restart with [`caddy run --resume`](/docs/command-line#caddy-run). +To get started with the API, try our [API tutorial](/docs/api-tutorial) or, if you only have a minute, our [API quick-start guide](/docs/quick-starts/api). + --- - **[POST /load](#post-load)** diff --git a/src/docs/markdown/caddyfile-tutorial.md b/src/docs/markdown/caddyfile-tutorial.md index 2f0bb45..2ccb669 100644 --- a/src/docs/markdown/caddyfile-tutorial.md +++ b/src/docs/markdown/caddyfile-tutorial.md @@ -4,7 +4,7 @@ title: Caddyfile Tutorial # Caddyfile Tutorial -This tutorial will teach you the basics of the HTTP Caddyfile so that you can quickly and easily produce good-looking, functional site configs. +This tutorial will teach you the basics of the [HTTP Caddyfile](/docs/caddyfile) so that you can quickly and easily produce good-looking, functional site configs. **Objectives:** - 🔲 First site diff --git a/src/docs/markdown/caddyfile.md b/src/docs/markdown/caddyfile.md index ed93f35..e973a59 100644 --- a/src/docs/markdown/caddyfile.md +++ b/src/docs/markdown/caddyfile.md @@ -24,8 +24,9 @@ The basic idea is that you first type the address of your site, then the feature ## Menu - #### [Quick start guide](/docs/quick-starts/caddyfile) -- #### [List of directives](/docs/caddyfile/directives) +- #### [Full Caddyfile tutorial](/docs/caddyfile-tutorial) - #### [Caddyfile concepts](/docs/caddyfile/concepts) +- #### [Directives](/docs/caddyfile/directives) - #### [Global options](/docs/caddyfile/options) diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index 9023001..767d489 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -26,7 +26,7 @@ Key points: - An optional **global options block** can be the very first thing in the file. - Otherwise, the first line of the Caddyfile is **always** the address(es) of the site to serve. -- All directives **must** go in a site block. There is no global scope or inheritence across site blocks. +- All directives and matchers **must** go in a site block. There is no global scope or inheritence across site blocks. - If there is **only one site block**, its curly braces `{ }` are optional. A Caddyfile consists of at least one or more site blocks, which always starts with one or more [addresses](#addresses) for the site. Any directives appearing before the address will be confusing to the parser. @@ -131,13 +131,13 @@ These are examples of valid addresses: - `localhost:8080` - `127.0.0.1` - `[::1]:2015` -- `example.com/foo` +- `example.com/foo/*` -From the address, Caddy can potentially infer the scheme, host, port, and path prefix of your site. The default port is 2015 unless [automatic HTTPS](/docs/automatic-https#activation) is activated, which changes it to the HTTPS port. +From the address, Caddy can potentially infer the scheme, host, port, and path of your site. The default port is 2015 unless [automatic HTTPS](/docs/automatic-https#activation) is activated, which changes it to the HTTPS port. If you specify a hostname, only requests with a matching Host header will be honored. In other words, if the site address is `localhost`, then Caddy will not match requests to `127.0.0.1`. -If multiple sites share the same definition, you can list all of them: +If multiple sites share the same definition, you can list all of them together: ``` localhost:8080, example.com, www.site.com @@ -190,7 +190,7 @@ redir /old-article.html /new-article.html Path matcher tokens must start with a forward slash `/`. -Note that [path matching](/docs/json/apps/http/servers/routes/match/path/) is an exact match by default; you must append a `*` for a fast prefix match. +Note that [path matching](/docs/json/apps/http/servers/routes/match/path/) is an exact match by default; you must append a `*` for a fast prefix match. Be aware that matching `/foo*` will also match `/foobar`; you might actually want `/foo/*` instead. ### Named matcher @@ -241,6 +241,8 @@ The following matcher modules are built-in: } ``` +Like directives, named matcher definitions must go inside the site blocks that use them. + ### Matcher examples diff --git a/src/docs/markdown/extending-caddy.md b/src/docs/markdown/extending-caddy.md index d3880a5..c664bb8 100644 --- a/src/docs/markdown/extending-caddy.md +++ b/src/docs/markdown/extending-caddy.md @@ -4,7 +4,7 @@ title: "Extending Caddy" # Extending Caddy -Caddy is easy to extend because of its modular architecture. Most Caddy extensions (or plugins) are called _modules_. To be clear, Caddy modules are distinct from [Go modules](https://github.com/golang/go/wiki/Modules) (but they are also Go modules). On this page, we refer to Caddy modules. +Caddy is easy to extend because of its modular architecture. Most kinds of Caddy extensions (or plugins) are known as _modules_ if they extend or plug into Caddy's configuration structure. To be clear, Caddy modules are distinct from [Go modules](https://github.com/golang/go/wiki/Modules) (but they are also Go modules). On this page, we refer to Caddy modules.