Docs: Document custom pages and patches

docs/src/SUMMARY.md

@@ -4,6 +4,7 @@
 
 - [Installing](./installing.md)
 - [Usage](./usage.md)
+  - [Custom Pages](./usage_custom_pages.md)
 - [Configuration](./config.md)
   - [Section: \[display\]](./config_display.md)
   - [Section: \[style\]](./config_style.md)

docs/src/config_directories.md

@@ -4,8 +4,9 @@ This section allows overriding some directory paths.
 
 ## `custom_pages_dir`
 
-Set the directory to be used to look up custom pages. Remember to use an
-absolute path. Variable expansion will not be performed on the path.
+Set the directory to be used to look up [custom
+pages](usage_custom_pages.html). Remember to use an absolute path. Variable
+expansion will not be performed on the path.
 
     [directories]
     custom_pages_dir = "/home/myuser/custom-tldr-pages/"

docs/src/usage_custom_pages.md

@@ -0,0 +1,42 @@
+# Custom Pages and Patches
+
+Tealdeer allows creating new custom pages, overriding existing pages as well as
+extending existing pages.
+
+The directory, where these custom pages and patches can be placed, follows OS
+conventions. On Linux, for example, the default location is
+`~/.local/share/tealdeer/pages/`. To print the path used on your system, simply
+run `tldr --show-paths`.
+
+The custom pages directory can be [overridden by the config
+file](config_directories.html).
+
+## Custom Pages
+
+To document internal command line tools, or if you want to replace an existing
+tldr page with one that's better suited for you, place a file with the name
+`<command>.page` in the custom pages directory. When calling `tldr <command>`,
+your custom page will be shown instead of the upstream version in the cache.
+
+Path:
+
+    $CUSTOM_PAGES_DIR/<command>.page
+
+Example:
+
+    ~/.local/share/tealdeer/pages/ufw.page
+
+## Custom Patches
+
+Sometimes you don't want to fully replace an existing upstream page, but just
+want to extend it with your own examples that you frequently need. In this
+case, use a file called `<command>.patch`, it will be appended to existing
+pages.
+
+Path:
+
+    $CUSTOM_PAGES_DIR/<command>.patch
+
+Example:
+
+    ~/.local/share/tealdeer/pages/ufw.patch