From ca844b35e93bb32d43ce433f650b1dbf9378891a Mon Sep 17 00:00:00 2001
From: Danilo Bargen <mail@dbrgn.ch>
Date: Mon, 20 Dec 2021 01:04:57 +0100
Subject: [PATCH] Docs: Document custom pages and patches

---
 docs/src/SUMMARY.md            |  1 +
 docs/src/config_directories.md |  5 ++--
 docs/src/usage_custom_pages.md | 42 ++++++++++++++++++++++++++++++++++
 3 files changed, 46 insertions(+), 2 deletions(-)
 create mode 100644 docs/src/usage_custom_pages.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index eb628c2..8aaac31 100644
--- a/docs/src/SUMMARY.md
+++ b/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)
diff --git a/docs/src/config_directories.md b/docs/src/config_directories.md
index 8340ad9..d894e90 100644
--- a/docs/src/config_directories.md
+++ b/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/"
diff --git a/docs/src/usage_custom_pages.md b/docs/src/usage_custom_pages.md
new file mode 100644
index 0000000..589479f
--- /dev/null
+++ b/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