mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-04-21 12:36:16 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Clarify uri syntax, replacement variables (#173)

Browse source 
- The syntax definition was confusing because it was mixing one-of options and optional arguments which are only relevant for certain options.

- Add notes about replacement capture groups. Wording could probably be improved here. Point is, capture groups are supported, using Golang's syntax (doesn't use Caddy's placeholder syntax, which can be a gotcha)

- Add similar directives section, mainly to point out that `handle_path` can be used instead in many situations to save a line. The note about `rewrite` is kinda redundant with the small paragraph at the top though. Should we move that explanation down into `Similar directives`?
This commit is contained in:
Francis Lavoie 2021-06-21 13:50:32 -04:00 • committed by GitHub
parent 75869ca9f3
commit 1ff5103c73
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

19
src/docs/markdown/caddyfile/directives/uri.md
View file

@ -11,10 +11,13 @@ This directive is distinct from [`rewrite`](rewrite) in that `uri` _partially_ c
## Syntax
Multiple different operations are supported:
```caddy-d
uri [<matcher>] strip_prefix|strip_suffix|replace|path_regexp \
<target> \
[<replacement> [<limit>]]
uri [<matcher>] strip_prefix <target>
uri [<matcher>] strip_suffix <target>
uri [<matcher>] replace <target> <replacement> [<limit>]
uri [<matcher>] path_regexp <target> <replacement>
```
- The first (non-matcher) argument specifies the operation:
@ -23,10 +26,18 @@ uri [<matcher>] strip_prefix|strip_suffix|replace|path_regexp \
- **replace** performs a substring replacement across the whole URI.
- **path_regexp** performs a regular expression replacement on the path portion of the URI.
- **&lt;target&gt;** is the prefix, suffix, or search string/regular expression. If a prefix, the leading forward slash may be omitted, since paths always start with a forward slash.
- **&lt;replacement&gt;** is the replacement string (only valid with `replace` and `path_regexp`).
- **&lt;replacement&gt;** is the replacement string (only valid with `replace` and `path_regexp`). Supports using capture groups with `$name` or `${name}` syntax, or with a number for the index, such as `$1`. See the [Go documentation](https://golang.org/pkg/regexp/#Regexp.Expand) for details.
- **&lt;limit&gt;** is an optional limit to the maximum number of replacements (only valid with `replace`).
## Similar directives
Some other directives can also manipulate the request URI.
- [`rewrite`](rewrite) will change the entire path and query to a new value, instead of doing a partial change like `uri` does.
- [`handle_path`](handle_path) does the same as [`handle`](handle), but it strips a prefix from the request before running its handlers. Can be used instead of `uri strip_prefix` to save a line of config in many situations.
## Examples
Strip `/api` from the beginning of all request paths: