Merge pull request 'docs: revamp minimal mode troubleshooting section' (#88) from fix/docs-troubleshooting-formatting into main

Reviewed-on: #88

docs/build-manual.py

@@ -160,6 +160,7 @@ SHELL_HEADS = frozenset(
     if jobs kitty ls man math mkdir mv nvim npm pacman paru pip pip3 pkg printf
     python python3 rm set shutdown source string sudo switch systemctl test time
     tmux touch trash type wget wezterm while yay zellij zypper
+    fish_default_key_bindings fish_vi_key_bindings
     """.split()
 )
 
@@ -212,7 +213,7 @@ PATH_LINE_RE = re.compile(r"^[~$][\w./{}-]*\.\w+$")
 # A leading "# in local.fish" / "# local.fish" comment names the file an
 # example belongs to; promote it to the fence title instead of leaving it
 # as a literal comment inside the code.
-FILENAME_COMMENT_RE = re.compile(r"^#\s*(?:in\s+)?([\w-]+\.\w+)\s*$")
+FILENAME_COMMENT_RE = re.compile(r"^#\s*(?:in\s+)?([$~\w./-]+\.\w+)\s*$")
 
 CELL_SPLIT = re.compile(r"\s{2,}")
 
@@ -621,7 +622,8 @@ def _inject_subheading_cards(body: str) -> str:
     cards = []
     for title in headings:
         safe_title = _jsx_attr_escape(title)
-        slug = re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")
+        slug = re.sub(r"[^\w\s-]", "", title.lower())
+        slug = re.sub(r"[-\s]+", "-", slug).strip("-")
         cards.append(f'  <LinkCard title="{safe_title}" href="#{slug}" />')
     
     cardgrid = "<CardGrid>\n" + "\n".join(cards) + "\n</CardGrid>\n\n"

docs/fish-config.index

@@ -292,8 +292,8 @@ local-config=## local.fish
 troubleshooting=# 11. TROUBLESHOOTING
 troubleshoot=# 11. TROUBLESHOOTING
 faq=# 11. TROUBLESHOOTING
-uninstall=## Uninstalling / Reverting to Backup
+uninstall=## Uninstalling and Reverting to Backup
-revert=## Uninstalling / Reverting to Backup
+revert=## Uninstalling and Reverting to Backup
 fish-version=## Fish Version Requirement
 version-req=## Fish Version Requirement
 disable-logging=## Disable Session Logging
@@ -307,7 +307,7 @@ missing-deps=## Missing Dependencies
 vi-mode=## Vi Mode Keybindings
 vi-trouble=## Vi Mode Keybindings
 emacs-mode=## Vi Mode Keybindings
-minimal-trouble=## Minimal Mode / Disabling Opinionated Features
+minimal-trouble=## What's with the C1-C6 stuff?
 
 # ── Section 12: Viewing This Manual ──────────────────────────
 viewing=# 12. VIEWING THIS MANUAL

docs/fish-config.md

@@ -128,7 +128,7 @@ The configuration uses a structured file tree:
     9.  Installation
     10. Personalization
     11. Troubleshooting
-        11.1 Uninstalling / Reverting to Backup
+        11.1 Uninstalling and Reverting to Backup
         11.2 Fish Version Requirement
         11.3 Disable Session Logging
         11.4 Change or Disable the Greeting
@@ -136,7 +136,7 @@ The configuration uses a structured file tree:
         11.6 Tool Init Does Nothing (Return Sentinel)
         11.7 Missing Dependencies
         11.8 Vi Mode Keybindings
-        11.9 Minimal Mode / Disabling Opinionated Features
+        11.9 What's with the C1-C6 stuff?
     12. Viewing This Manual
 
 ---
@@ -3137,7 +3137,7 @@ local.fish in turn sources secrets.fish when it exists.
 
 This section covers common issues, their solutions, and how to safely revert changes or uninstall the configuration entirely.
 
-## Uninstalling / Reverting to Backup
+## Uninstalling and Reverting to Backup
 
 The installation step backs up any existing config to `~/.config/fish.bak`.
 To revert:
@@ -3306,7 +3306,7 @@ See Dependency Catalog for the full list grouped by tier
 
 This config enables Vi mode by default (via C3 overrides), replacing the
 standard Emacs-style bindings. If Vi mode interferes with your workflow,
-override it in `local.fish`:
+override it in `local.fish` (See Personalization):
 
     # $__fish_user_dots_path/local.fish
     fish_default_key_bindings
@@ -3322,24 +3322,31 @@ overrides):
 See C3 — Key and Environment Overrides for the full list of
 what C3 controls.
 
-## Minimal Mode / Disabling Opinionated Features
+## What's with the C1-C6 stuff?
 
-Disable all opinionated features at once:
+This configuration groups its opinionated behaviors into six categories (C1–C6), allowing you to selectively disable features that conflict with your workflow. Disabling all of them leaves you with a "Minimal Mode" shell that only manages PATH, XDG variables, and your `local.fish` overrides.
+
+    Category   Description
+    ──────────────────────────────────────────────────────────────────────────
+    C1         Command Shadows (aliases that replace default tools)
+    C2         Auto-Exec (background tasks and startup side-effects)
+    C3         Key & Env Overrides (Vi mode, PAGER)
+    C4         Terminal Integrations (Kitty, WezTerm)
+    C5         Logging and Capture (session logs, command duration)
+    C6         Greeting & First-Run UI (custom startup banner)
+
+Disable all opinionated features at once (Minimal Mode):
 
     set -U __fish_config_opinionated 0
 
-This turns off all six categories (aliases, auto-exec, overrides,
-integrations, logging, greeting) — leaving a clean shell with only PATH,
-XDG variables, and local.fish sourcing.
-
 Disable a single category:
 
-    set -U __fish_config_op_aliases off         # C1 — command shadows
+    set -U __fish_config_op_aliases off         # C1
-    set -U __fish_config_op_autoexec off        # C2 — startup side-effects
+    set -U __fish_config_op_autoexec off        # C2
-    set -U __fish_config_op_overrides off       # C3 — key/env overrides
+    set -U __fish_config_op_overrides off       # C3
-    set -U __fish_config_op_integrations off    # C4 — terminal integrations
+    set -U __fish_config_op_integrations off    # C4
-    set -U __fish_config_op_logging off         # C5 — logging and capture
+    set -U __fish_config_op_logging off         # C5
-    set -U __fish_config_op_greeting off        # C6 — greeting
+    set -U __fish_config_op_greeting off        # C6
 
 Keep one category active under a master disable:
 
@@ -3350,10 +3357,7 @@ Re-enable everything:
 
     set -Ue __fish_config_opinionated
 
-Or use the interactive TUI: `config-settings`.
+For an interactive alternative to setting these variables by hand, run `config-settings`.
-
-See Opinionated Components (Minimal Mode) for the full
-component reference tables.
 
 ---
 

docs/manual/00-table-of-contents.md

@@ -43,7 +43,7 @@ sidebar:
     9.  Installation
     10. Personalization
     11. Troubleshooting
-        11.1 Uninstalling / Reverting to Backup
+        11.1 Uninstalling and Reverting to Backup
         11.2 Fish Version Requirement
         11.3 Disable Session Logging
         11.4 Change or Disable the Greeting
@@ -51,7 +51,7 @@ sidebar:
         11.6 Tool Init Does Nothing (Return Sentinel)
         11.7 Missing Dependencies
         11.8 Vi Mode Keybindings
-        11.9 Minimal Mode / Disabling Opinionated Features
+        11.9 What's with the C1-C6 stuff?
     12. Viewing This Manual
 
 ---

docs/manual/11-troubleshooting.md

@@ -14,7 +14,7 @@ helpKeywords:
 
 This section covers common issues, their solutions, and how to safely revert changes or uninstall the configuration entirely.
 
-## Uninstalling / Reverting to Backup
+## Uninstalling and Reverting to Backup
 
 The installation step backs up any existing config to `~/.config/fish.bak`.
 To revert:
@@ -91,7 +91,7 @@ Re-enable:
 
     set -Ue __fish_config_op_logging
 
-See [C5 — Logging and Capture](/07-customization/#c5--logging-and-capture) for the full component breakdown.
+See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full component breakdown.
 
 ## Change or Disable the Greeting
 
@@ -112,7 +112,7 @@ testing):
 
     set -Ue __fish_config_first_run_complete
 
-See [C6 — Greeting and First-Run UI](/07-customization/#c6--greeting-and-first-run-ui) for details.
+See [C6 — Greeting and First-Run UI](/07-customization/#c6-greeting-and-first-run-ui) for details.
 
 ## Secrets and Machine-Local Configuration
 
@@ -183,7 +183,7 @@ See [Dependency Catalog](/06-dependency-catalog/) for the full list grouped by t
 
 This config enables Vi mode by default (via C3 overrides), replacing the
 standard Emacs-style bindings. If Vi mode interferes with your workflow,
-override it in `local.fish`:
+override it in `local.fish` (See [Personalization](/10-personalization/)):
 
     # $__fish_user_dots_path/local.fish
     fish_default_key_bindings
@@ -196,27 +196,34 @@ overrides):
 
     set -U __fish_config_op_overrides off
 
-See [C3 — Key and Environment Overrides](/07-customization/#c3--key-and-environment-overrides) for the full list of
+See [C3 — Key and Environment Overrides](/07-customization/#c3-key-and-environment-overrides) for the full list of
 what C3 controls.
 
-## Minimal Mode / Disabling Opinionated Features
+## What's with the C1-C6 stuff?
 
-Disable all opinionated features at once:
+This configuration groups its opinionated behaviors into six categories (C1–C6), allowing you to selectively disable features that conflict with your workflow. Disabling all of them leaves you with a "Minimal Mode" shell that only manages PATH, XDG variables, and your `local.fish` overrides.
+
+    Category   Description
+    ──────────────────────────────────────────────────────────────────────────
+    C1         [Command Shadows](/07-customization/#c1-command-shadows) (aliases that replace default tools)
+    C2         [Auto-Exec](/07-customization/#c2-auto-exec) (background tasks and startup side-effects)
+    C3         [Key & Env Overrides](/07-customization/#c3-key-and-environment-overrides) (Vi mode, PAGER)
+    C4         [Terminal Integrations](/07-customization/#c4-terminal-integrations) (Kitty, WezTerm)
+    C5         [Logging and Capture](/07-customization/#c5-logging-and-capture) (session logs, command duration)
+    C6         [Greeting & First-Run UI](/07-customization/#c6-greeting-and-first-run-ui) (custom startup banner)
+
+Disable all opinionated features at once (Minimal Mode):
 
     set -U __fish_config_opinionated 0
 
-This turns off all six categories (aliases, auto-exec, overrides,
-integrations, logging, greeting) — leaving a clean shell with only PATH,
-XDG variables, and local.fish sourcing.
-
 Disable a single category:
 
-    set -U __fish_config_op_aliases off         # C1 — command shadows
+    set -U __fish_config_op_aliases off         # C1
-    set -U __fish_config_op_autoexec off        # C2 — startup side-effects
+    set -U __fish_config_op_autoexec off        # C2
-    set -U __fish_config_op_overrides off       # C3 — key/env overrides
+    set -U __fish_config_op_overrides off       # C3
-    set -U __fish_config_op_integrations off    # C4 — terminal integrations
+    set -U __fish_config_op_integrations off    # C4
-    set -U __fish_config_op_logging off         # C5 — logging and capture
+    set -U __fish_config_op_logging off         # C5
-    set -U __fish_config_op_greeting off        # C6 — greeting
+    set -U __fish_config_op_greeting off        # C6
 
 Keep one category active under a master disable:
 
@@ -227,9 +234,6 @@ Re-enable everything:
 
     set -Ue __fish_config_opinionated
 
-Or use the interactive TUI: `config-settings`.
+For an interactive alternative to setting these variables by hand, run `config-settings`.
-
-See [Opinionated Components (Minimal Mode)](/07-customization/#opinionated-components-minimal-mode) for the full
-component reference tables.
 
 ---

docs/manual/index.md

@@ -35,7 +35,7 @@ output, file contents, and secrets printed to the terminal. Nothing leaves
 your machine, but the files persist locally.
 - Disable all logging with: `set -U __fish_config_op_logging off`
 - Prefer a menu? Run the interactive picker: `config-settings`
-- See [C5 — Logging and Capture](/07-customization/#c5--logging-and-capture) for the full breakdown.
+- See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full breakdown.
 
 The configuration uses a structured file tree: