From 2b127fd67e7c0eef59efdff907dcf63da4dfcbe1 Mon Sep 17 00:00:00 2001
From: Niklas Mohrin <dev@niklasmohrin.de>
Date: Fri, 3 Oct 2025 20:59:22 +0200
Subject: [PATCH] Highlight code examples in user docs (#440)

* Highlight code examples in user docs
* Add missing quotes to archive_source example
---
 docs/src/config.md             |  8 +++++--
 docs/src/config_directories.md | 12 +++++++----
 docs/src/config_display.md     | 20 +++++++++++------
 docs/src/config_search.md      | 16 ++++++++------
 docs/src/config_style.md       | 12 ++++++++---
 docs/src/config_updates.md     | 39 +++++++++++++++++++++-------------
 docs/src/installing.md         | 16 ++++++++++----
 docs/src/usage_custom_pages.md | 16 ++++++++++----
 8 files changed, 94 insertions(+), 45 deletions(-)

diff --git a/docs/src/config.md b/docs/src/config.md
index b0bf922..a662b57 100644
--- a/docs/src/config.md
+++ b/docs/src/config.md
@@ -9,11 +9,15 @@ The configuration file path follows OS conventions (e.g.
 `$XDG_CONFIG_HOME/tealdeer/config.toml` on Linux). The paths can be queried
 with the following command:
 
-    $ tldr --show-paths
+```shell
+$ tldr --show-paths
+```
 
 Creating the config file can be done manually or with the help of `tldr`:
 
-    $ tldr --seed-config
+```shell
+$ tldr --seed-config
+```
 
 On Linux, this will usually be `~/.config/tealdeer/config.toml`.
 
diff --git a/docs/src/config_directories.md b/docs/src/config_directories.md
index b194dbb..507bd27 100644
--- a/docs/src/config_directories.md
+++ b/docs/src/config_directories.md
@@ -8,8 +8,10 @@ Override the cache directory. Remember to use an absolute path. Variable
 expansion will not be performed on the path. If the directory does not yet
 exist, it will be created.
 
-    [directories]
-    cache_dir = "/home/myuser/.tealdeer-cache/"
+```toml
+[directories]
+cache_dir = "/home/myuser/.tealdeer-cache/"
+```
 
 If no `cache_dir` is specified, tealdeer will fall back to a location that
 follows OS conventions. On Linux, it will usually be at `~/.cache/tealdeer/`.
@@ -21,5 +23,7 @@ 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/"
+```toml
+[directories]
+custom_pages_dir = "/home/myuser/custom-tldr-pages/"
+```
diff --git a/docs/src/config_display.md b/docs/src/config_display.md
index 56b5cd3..78656a4 100644
--- a/docs/src/config_display.md
+++ b/docs/src/config_display.md
@@ -6,8 +6,10 @@ In the `display` section you can configure the output format.
 
 Specifies whether the pager should be used by default or not (default `false`).
 
-    [display]
-    use_pager = true
+```toml
+[display]
+use_pager = true
+```
 
 When enabled, `less -R` is used as pager. To override the pager command used,
 set the `PAGER` environment variable.
@@ -19,15 +21,19 @@ NOTE: This feature is not available on Windows.
 Set this to enforce more compact output, where empty lines are stripped out
 (default `false`).
 
-    [display]
-    compact = true
+```toml
+[display]
+compact = true
+```
 
 ## `show_title`
 
 Display the command name at the top of the page output (default `false`).
 
-    [display]
-    show_title = true
+```toml
+[display]
+show_title = true
+```
 
 When enabled, the command name will be displayed at the top of the output,
-styled with the `command_name` style configuration.
\ No newline at end of file
+styled with the `command_name` style configuration.
diff --git a/docs/src/config_search.md b/docs/src/config_search.md
index d368159..28e00d6 100644
--- a/docs/src/config_search.md
+++ b/docs/src/config_search.md
@@ -9,9 +9,11 @@ The list of languages that should be considered when searching.
 If unspecified, the list of languages will be inferred from the `LANG` and `LANGUAGE` environment variables.
 Either way, the language used can be overwritten using the `--language` command line flag.
 
-    [search]
-    # Show pages in German if available, otherwise show in English
-    languages = ["de", "en"]
+```toml
+[search]
+# Show pages in German if available, otherwise show in English
+languages = ["de", "en"]
+```
 
 ## `platforms`
 
@@ -24,6 +26,8 @@ Tealdeer searches the platforms in order of appearance in this list.
 The default list of platforms is `["current", "common", "all"]`.
 The list of platforms can be overwritten using the `--platform` command line flag.
 
-    [search]
-    # Search for linux and common, and then search windows before trying the remaining platforms
-    platforms = ["linux", "common", "windows", "all"]
+```toml
+[search]
+# Search for linux and common, and then search windows before trying the remaining platforms
+platforms = ["linux", "common", "windows", "all"]
+```
diff --git a/docs/src/config_style.md b/docs/src/config_style.md
index 190df4c..593a5b5 100644
--- a/docs/src/config_style.md
+++ b/docs/src/config_style.md
@@ -26,16 +26,22 @@ Colors can be specified in one of three ways:
 
   Example:
 
-      foreground = "green"
+  ```toml
+  foreground = "green"
+  ```
 
 - 256 color ANSI code (*tealdeer v1.5.0+*)
 
   Example:
 
-      foreground = { ansi = 4 }
+  ```toml
+  foreground = { ansi = 4 }
+  ```
 
 - 24-bit RGB color (*tealdeer v1.5.0+*)
 
   Example:
 
-      background = { rgb = { r = 255, g = 255, b = 255 } }
+  ```toml
+  background = { rgb = { r = 255, g = 255, b = 255 } }
+  ```
diff --git a/docs/src/config_updates.md b/docs/src/config_updates.md
index cc5868e..9acba55 100644
--- a/docs/src/config_updates.md
+++ b/docs/src/config_updates.md
@@ -13,8 +13,10 @@ default.
 Specifies whether the auto-update feature should be enabled (defaults to
 `false`).
 
-    [updates]
-    auto_update = true
+```toml
+[updates]
+auto_update = true
+```
 
 ### `auto_update_interval_hours`
 
@@ -22,9 +24,11 @@ Duration, since the last cache update, after which the cache will be
 refreshed (defaults to 720 hours). This parameter is ignored if `auto_update`
 is set to `false`.
 
-    [updates]
-    auto_update = true
-    auto_update_interval_hours = 24
+```toml
+[updates]
+auto_update = true
+auto_update_interval_hours = 24
+```
 
 ## Download configuration
 
@@ -35,20 +39,24 @@ If unspecified, the languages listed in the `search.languages` setting are used.
 Thus, this setting is the most useful to instruct tealdeer to download pages in additional languages that are not searched by default.
 Either way, the language used can be overwritten using the `--language` command line flag.
 
-    [search]
-    languages = ["de", "en"]
+```toml
+[search]
+languages = ["de", "en"]
 
-    [updates]
-    # sometimes I like to read the Italian description
-    download_languages = ["de", "en", "it"]
+[updates]
+# sometimes I like to read the Italian description
+download_languages = ["de", "en", "it"]
+```
 
 ### `archive_source`
 
 URL for the location of the tldr pages archive. By default the pages are
 fetched from the latest `tldr-pages/tldr` GitHub release.
 
-    [updates]
-    archive_source = https://my-company.example.com/tldr/
+```toml
+[updates]
+archive_source = "https://my-company.example.com/tldr/"
+```
 
 ### `tls_backend`
 
@@ -62,9 +70,10 @@ Available options:
   - Secure Transport on macOS
   - OpenSSL on other platforms
 
-    [updates]
-    tls_backend = "native-tls"
-
+```toml
+[updates]
+tls_backend = "native-tls"
+```
 
 [rustls]: https://github.com/rustls/rustls
 [rustls-webpki]: https://github.com/rustls/webpki
diff --git a/docs/src/installing.md b/docs/src/installing.md
index 39de050..0bee062 100644
--- a/docs/src/installing.md
+++ b/docs/src/installing.md
@@ -38,21 +38,29 @@ Simply download the binary for your platform and run it!
 
 Build and install the tool via cargo...
 
-    $ cargo install tealdeer
+```shell
+$ cargo install tealdeer
+```
 
 ## Build From Source
 
 Release build:
 
-    $ cargo build --release
+```shell
+$ cargo build --release
+```
 
 Release build with bundled CA roots:
 
-    $ cargo build --release --no-default-features --features rustls-with-webpki-roots
+```shell
+$ cargo build --release --no-default-features --features rustls-with-webpki-roots
+```
 
 Debug build with logging support:
 
-    $ cargo build --features logging
+```shell
+$ cargo build --features logging
+```
 
 (To enable logging at runtime, export the `RUST_LOG=tldr=debug` env variable.)
 
diff --git a/docs/src/usage_custom_pages.md b/docs/src/usage_custom_pages.md
index d5d0f89..c73bf90 100644
--- a/docs/src/usage_custom_pages.md
+++ b/docs/src/usage_custom_pages.md
@@ -28,11 +28,15 @@ your custom page will be shown instead of the upstream version in the cache.
 
 Path:
 
-    $CUSTOM_PAGES_DIR/<command>.page.md
+```plain
+$CUSTOM_PAGES_DIR/<command>.page.md
+```
 
 Example:
 
-    ~/.local/share/tealdeer/pages/ufw.page.md
+```plain
+~/.local/share/tealdeer/pages/ufw.page.md
+```
 
 ## Custom Patches
 
@@ -43,8 +47,12 @@ pages.
 
 Path:
 
-    $CUSTOM_PAGES_DIR/<command>.patch.md
+```plain
+$CUSTOM_PAGES_DIR/<command>.patch.md
+```
 
 Example:
 
-    ~/.local/share/tealdeer/pages/ufw.patch.md
+```plain
+~/.local/share/tealdeer/pages/ufw.patch.md
+```