Extend remap documentation

lycheeverse · Jul 5, 2023 · 870953c · 870953c
1 parent def7c59
commit 870953c
Show file tree

Hide file tree

Showing 2 changed files with 30 additions and 4 deletions.
diff --git a/recipes/migration.md b/recipes/migration.md
@@ -13,8 +13,8 @@ lychee --remap 'example.com example.org' -- https://example.com/sitemap.xml
 ```
 
 The `--remap` option takes a list of space-separated pairs of strings.
-The first string is the old domain and the second string is the new domain.
-The old domain is replaced with the new domain in all links.
+The first string is the old URL pattern and the second string is the new URL pattern.
+In this example, the old domain is replaced with the new domain in all links.
 
 You can use this option multiple times to remap multiple domains and you can use
 regular expressions.
@@ -39,5 +39,26 @@ lychee --remap 'example.com example.org' \
        https://example.com/sitemap.xml 
 ```
 
-For more information about the `--remap` option, see [#620](https://github.com/lycheeverse/lychee/pull/620) and the [example config file](https://github.com/lycheeverse/lychee/blob/4d31fb777dc6ddb0f870336c0875c218c5014624/lychee.example.toml).
+Remap is a powerful feature.
+Instead of just replacing domains, you can also use regular expressions to
+replace parts of the URL.
+
+For example, if you want to migrate from GitHub to GitLab, you can use this
+command:
+
+```bash
+lychee --remap 'github.com/(.*) gitlab.com/$1' ...
+```
+
+This will replace all links from `github.com` to `gitlab.com` while keeping the
+rest of the URL intact.
+
+You can also use named capture groups to replace parts of the URL with a
+different name:
+
+```bash
+lychee --remap 'github.com/(?P<org>.*)/(?P<repo>.*) gitlab.com/$org/$repo' ...
+```
+
+For more information about the `--remap` option, see [#620](https://github.com/lycheeverse/lychee/pull/620), [#1129](https://github.com/lycheeverse/lychee/issues/1129), and the [example config file](https://github.com/lycheeverse/lychee/blob/4d31fb777dc6ddb0f870336c0875c218c5014624/lychee.example.toml).
 
diff --git a/usage/config.md b/usage/config.md
@@ -90,7 +90,12 @@ method = "get"
 headers = []
 
 # Remap URI matching pattern to different URI.
-remap = [ "https://example.com http://example.invalid" ]
+# This also supports (named) capturing groups.
+remap = [ 
+    "https://example.com http://example.invalid",
+    "https://example.com/(.*) http://example.org/$1",
+    "https://github.com/(?P<org>.*)/(?P<repo>.*) https://gitlab.com/$org/$repo",
+]
 
 # Base URL or website root directory to check relative URLs.
 base = "https://example.com"