rootiest/fish-config
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'docs: revamp minimal mode troubleshooting section' (#88) from fix/docs-troubleshooting-formatting into main
Generate documentation / build-docs (push) Successful in 3m1s
Details

Browse Source 
Reviewed-on: #88
This commit was merged in pull request #88.
This commit is contained in:
Rootiest
2026-07-27 21:07:22 +00:00
parent 6b484599ae 12ee2bac89
commit 11a9db5fad
7 changed files with 1383 additions and 1792 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/build-manual.py
+4 -2
View File
@@ -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.1
+1324 -1743
View File
File diff suppressed because it is too large Load Diff
docs/fish-config.index
+3 -3
View File
@@ -292,8 +292,8 @@ local-config=## local.fish
troubleshooting=# 11. TROUBLESHOOTING
troubleshoot=# 11. TROUBLESHOOTING
faq=# 11. TROUBLESHOOTING
uninstall=## Uninstalling / Reverting to Backup
revert=## Uninstalling / Reverting to Backup
uninstall=## Uninstalling and 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
+24 -20
View File
@@ -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_autoexec off # C2 — startup side-effects
set -U __fish_config_op_overrides off # C3 — key/env overrides
set -U __fish_config_op_integrations off # C4 — terminal integrations
set -U __fish_config_op_logging off # C5 — logging and capture
set -U __fish_config_op_greeting off # C6 — greeting
set -U __fish_config_op_aliases off # C1
set -U __fish_config_op_autoexec off # C2
set -U __fish_config_op_overrides off # C3
set -U __fish_config_op_integrations off # C4
set -U __fish_config_op_logging off # C5
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`.
See Opinionated Components (Minimal Mode) for the full
component reference tables.
For an interactive alternative to setting these variables by hand, run `config-settings`.
---
docs/manual/00-table-of-contents.md
+2 -2
View File
@@ -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
+25 -21
View File
@@ -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_autoexec off # C2 — startup side-effects
set -U __fish_config_op_overrides off # C3 — key/env overrides
set -U __fish_config_op_integrations off # C4 — terminal integrations
set -U __fish_config_op_logging off # C5 — logging and capture
set -U __fish_config_op_greeting off # C6 — greeting
set -U __fish_config_op_aliases off # C1
set -U __fish_config_op_autoexec off # C2
set -U __fish_config_op_overrides off # C3
set -U __fish_config_op_integrations off # C4
set -U __fish_config_op_logging off # C5
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`.
See [Opinionated Components (Minimal Mode)](/07-customization/#opinionated-components-minimal-mode) for the full
component reference tables.
For an interactive alternative to setting these variables by hand, run `config-settings`.
---
docs/manual/index.md
+1 -1
View File
@@ -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: