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

docs(site): improve UI, add catppuccin theme, fix MDX bugs

Browse Source
This commit is contained in:
Rootiest
2026-07-27 23:27:09 -04:00
parent 2b9b8e495c
commit 1972ea5bb9
27 changed files with 547 additions and 530 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/build-manual.py
+25 -3
View File
@@ -308,7 +308,8 @@ def _as_ruled_table(para: list[str]) -> str | None:
# placeholders like <session> or brace globs — code-span protects them
# instead of rejecting the whole table.
def cell(text: str, code: bool) -> str:
return _cell(text, code or "<" in text or "{" in text)
needs_protection = ("<" in text or "{" in text) and "`" not in text
return _cell(text, code or needs_protection)
out = [f"| {' | '.join(header)} |", "|" + "|".join(["---"] * n) + "|"]
for row in rows:
@@ -658,6 +659,7 @@ def build_site(root: Path, out: Path) -> list[dict]:
entries = build_entries(functions, link=lambda n: _entry_link(n, functions))
sidebar: list[dict] = [{"label": "Home", "link": "/"}]
standard_groups: dict = {}
functions_group: dict = {}
functions_index_target = None
functions_index_fm = None
@@ -676,8 +678,28 @@ def build_site(root: Path, out: Path) -> list[dict]:
target.parent.mkdir(parents=True, exist_ok=True)
body = _inject_subheading_cards(body)
_write_prettified(target, _page_fm(fm), prettify(body))
if rel.name not in ("index.md", "404.md"):
sidebar.append({"label": fm["title"], "link": "/" + rel.stem + "/"})
if len(rel.parts) > 1:
group_dir = rel.parts[0]
if rel.name == "index.md":
group = {
"label": fm["title"],
"collapsed": True,
"items": [{"label": "Categories", "link": f"/{group_dir}/"}]
}
standard_groups[group_dir] = group
sidebar.append(group)
elif rel.name != "404.md":
if group_dir in standard_groups:
standard_groups[group_dir]["items"].append({
"label": fm["title"],
"link": f"/{group_dir}/{rel.stem}/"
})
else:
sidebar.append({"label": fm["title"], "link": f"/{group_dir}/{rel.stem}/"})
else:
if rel.name not in ("index.md", "404.md"):
sidebar.append({"label": fm["title"], "link": "/" + rel.stem + "/"})
continue
# Section 5: category index page keeps its slot; entries explode.
docs/fish-config.index
+6 -6
View File
@@ -255,12 +255,12 @@ greeting=## C6 — Greeting and First-Run UI
# ── Prompt and Theme ──────────────────────────────────────────
prompt-theme=## Prompt and Theme
starship=#### Starship
fallback-prompt=#### Catppuccin Fallback Prompt
catppuccin-prompt=#### Catppuccin Fallback Prompt
nim-prompt=#### Catppuccin Fallback Prompt
fzf-theme=#### FZF
catppuccin-theme=#### Catppuccin Mocha Syntax Highlighting
starship=### Starship
fallback-prompt=### Catppuccin Fallback Prompt
catppuccin-prompt=### Catppuccin Fallback Prompt
nim-prompt=### Catppuccin Fallback Prompt
fzf-theme=### FZF
catppuccin-theme=### Catppuccin Mocha Syntax Highlighting
# ── Section 9: Fisher Plugins ─────────────────────────────────
plugins=# 9. FISHER PLUGINS
docs/fish-config.md
+65 -69
View File
@@ -29,28 +29,16 @@ The underlying `config-help` function is also available directly.
A production-grade Fish shell configuration targeting Fish 4.x. It provides:
- Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less)
- Drop-in replacements for common Unix tools (`ls`, `cat`, `rm`, `du`, `ping`, `less`)
- Deep Kitty and WezTerm terminal integration: tab/window/pane management from
the command line
- Optional session logging: terminal scrollback, tmux/zellij panes, and
paru/yay output captured to ~/.terminal_history (off by default; see below)
paru/yay output captured to `~/.terminal_history` (off by default; see C5 Logging)
- Automatic Python virtualenv activation on directory change
- Cross-platform package management via pkg and fish-deps
- AI scaffolding helpers for Claude Code and Antigravity
- Catppuccin Mocha color theme throughout
CAUTION: **SESSION LOGGING**
If enabled, this configuration can silently record terminal output to
`~/.terminal_history`: Kitty scrollback on window close, live tmux pane
streams, zellij pane snapshots on exit, and full paru/yay output. These logs
can contain command output, file contents, and secrets printed to the
terminal. Nothing leaves your machine, but the files persist locally. Logging
is off unless you turn it on.
- Enable all logging with: `set -U __fish_config_op_logging on`
- Prefer a menu? Run the interactive picker: `config-settings`
- Turn it back off with: `set -U __fish_config_op_logging off` (or erase the variable)
- See C5 — Logging and Capture for the full breakdown.
The configuration uses a structured file tree:
~/.config/fish/
@@ -157,7 +145,7 @@ Override them in local.fish (see Section 10, Personalization).
| `XDG_DATA_HOME` | `~/.local/share` |
| `XDG_STATE_HOME` | `~/.local/state` |
Tools that respect XDG are directed to these paths rather than polluting $HOME.
Tools that respect XDG are directed to these paths rather than polluting `$HOME`.
## Tool Homes (XDG-compliant)
@@ -401,7 +389,7 @@ some expand differently in Kitty vs WezTerm vs other terminals.
These abbreviations control the terminal emulator. Each has a Kitty
variant and a WezTerm variant; the correct one is inserted based on
$TERM or $TERM_PROGRAM.
`$TERM` or `$TERM_PROGRAM`.
:w New OS window
:wv Split pane horizontally (new pane below)
@@ -2639,6 +2627,7 @@ The install priority for each tool:
This section explains how to adapt the configuration to your specific workflow, including local machine overrides and opinionated component toggles.
## Machine-local Configuration
Place machine-specific settings that should not be committed to git in:
@@ -2661,6 +2650,7 @@ Opt out by setting `__fish_user_dots_symlink` to a falsy value, or toggling
removes any existing link. It only ever manages a symlink and never clobbers a
real file or directory at that path.
## Secrets and API Keys
$__fish_user_dots_path/secrets.fish
@@ -2672,6 +2662,7 @@ committed. It is sourced by local.fish directly, not by config.fish.
session, so it and its companion secrets.fish can override anything set
earlier.
## Overriding Configuration Variables
Any variable set in local.fish after the main config loads takes effect.
@@ -2680,23 +2671,25 @@ Example: to increase the scrollback history limit:
# in local.fish
set -gx SCROLLBACK_HISTORY_MAX_FILES 200
## Fish Universal Variables
Some settings (fzf colors, theme) are stored in fish_variables via
`set -U`. These are machine-local and git-ignored. Do not commit
fish_variables.
## Opinionated Components (Minimal Mode)
Every opinionated piece of this config is active by default but can be
switched off through six category opt-out variables, each evaluated via
__fish_variable_check. Set a variable to any falsy value (0, false, no,
`__fish_variable_check`. Set a variable to any falsy value (0, false, no,
off, n) to disable its category; erase it or set a truthy value (1, true,
yes, on, y) to re-enable. Unset means enabled — except for C5 logging, which
is opt-in (see below).
An explicit per-category truthy value takes precedence over the master
switch: setting __fish_config_opinionated=0 disables all unset categories,
switch: setting `__fish_config_opinionated`=0 disables all unset categories,
but a category with an explicit truthy value remains enabled regardless.
C5 (logging) is the one exception to "unset means enabled". Because it
@@ -2770,9 +2763,10 @@ NOTE:
- Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them.
- On CachyOS, the distro fish config's own aliases, history override, and bang-bang bindings are stripped per category as well.
## Prompt and Theme
#### Starship
### Starship
The primary prompt is Starship, initialized by conf.d/starship.fish.
Configure it via ~/.config/starship.toml.
@@ -2784,7 +2778,7 @@ markers on the prompt line itself. This allows ov to use them as sticky
section headers when browsing scrollback logs. Without Starship, fish's
built-in prompt handles these markers automatically.
#### Catppuccin Fallback Prompt
### Catppuccin Fallback Prompt
When Starship is absent or C3 overrides are disabled, a built-in nim-style
two-line prompt activates from functions/fish_prompt.fish. No external
@@ -2814,7 +2808,7 @@ active Docker context is also shown (if non-default):
✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt
Fri Jun 12 00:51:21 2026 ← success (no ✘)
#### FZF
### FZF
FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in
integrations/fzf.fish. The colors applied:
@@ -2825,7 +2819,7 @@ integrations/fzf.fish. The colors applied:
To customize, override FZF_DEFAULT_OPTS in local.fish.
#### Catppuccin Mocha Syntax Highlighting
### Catppuccin Mocha Syntax Highlighting
The Catppuccin Mocha theme ships with this config in themes/ and is applied
on first run via `conf.d/first_run.fish`. Colors are stored in fish_variables
@@ -2833,7 +2827,7 @@ on first run via `conf.d/first_run.fish`. Colors are stored in fish_variables
fish_config theme save "Catppuccin Latte"
---
`---`
# 8. COMPONENTS REFERENCE
@@ -2843,7 +2837,7 @@ category variable.
## C1 — Command Shadows
Disabling __fish_config_op_aliases restores standard system behavior for
Disabling `__fish_config_op_aliases` restores standard system behavior for
all of these commands.
Command / Alias Active behavior Disabled fallback
@@ -2875,7 +2869,7 @@ are permanently deleted, not trashed. There is no intermediate safety net.
## C2 — Startup Side-Effects
These run automatically without any user action. Disabling
__fish_config_op_autoexec prevents all of them.
`__fish_config_op_autoexec` prevents all of them.
Component Trigger What it does
───────────────────────────────────────────────────────────────────────────
@@ -2895,15 +2889,15 @@ wrapper generation, no automatic venv activation, no WakaTime reporting,
no auto-pull (the PWD handler is never registered), and the user-dots
convenience symlink is not created. The symlink is git-ignored and only ever
managed as a symlink — a real file or directory at that path is left untouched.
The symlink has its own opt-out independent of C2: set __fish_user_dots_symlink
The symlink has its own opt-out independent of C2: set `__fish_user_dots_symlink`
to a falsy value (or toggle "Dots link" off on the config-settings Paths page)
to stop generating it and remove any existing link — honoured even when C2 is
enabled. Managed by the __fish_user_dots_link helper.
The first-run completion marker (__fish_config_first_run_complete) is still
enabled. Managed by the `__fish_user_dots_link` helper.
The first-run completion marker (`__fish_config_first_run_complete`) is still
set so the init does not re-run on subsequent shells.
Python venv activation fires on every directory change. If a directory uses
direnv (.envrc present), direnv takes priority and auto-venv is skipped for
direnv (`.envrc` present), direnv takes priority and auto-venv is skipped for
that directory.
Auto-pull fast-forwards opted-in repositories in the background when you cd
@@ -2912,13 +2906,13 @@ the `auto-pull` command (see its entry in the functions reference). It only
ever fast-forwards a clean repo whose branch has an upstream — never rebases,
merges, or overwrites work — so it is a no-op on dirty trees, divergent
branches, or repos without a remote. The handler fires once per repo entry
(not on every sub-directory cd). The registry is machine-local at
(not on every sub-directory `cd`). The registry is machine-local at
`$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed.
## C3 — Key and Environment Overrides
These change fundamental shell behavior: how keys work, which pager opens,
and what the prompt looks like. Disabling __fish_config_op_overrides removes
and what the prompt looks like. Disabling `__fish_config_op_overrides` removes
all of them.
Override What it replaces or sets
@@ -2940,8 +2934,8 @@ all of them.
FZF_DEFAULT_OPTS FZF themed to Catppuccin Mocha colors
Right prompt fish_right_prompt: exit code (on failure) + dim timestamp; always rendered; Docker context added when starship+C3 active
The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish, and
six expand_bang_*.fish functions. All are gated together — disabling C3
The bang-bang system spans `key_bindings.fish`, `abbr.fish`, `puffer.fish`, and
six `expand_bang_*.fish` functions. All are gated together — disabling C3
removes the entire bang-expansion system at once.
When C3 is disabled, `exit` falls back to `builtin exit` with no scrollback
@@ -2951,11 +2945,11 @@ is independently controlled by C5 (see below).
## C4 — Terminal and Tool Integration
These features couple the shell to specific external tools. Disabling
__fish_config_op_integrations disables all of them.
`__fish_config_op_integrations` disables all of them.
Component Requires
───────────────────────────────────────────────────────────────────────────
~60 Kitty/WezTerm abbrs Active Kitty or WezTerm session
≈ 60 Kitty/WezTerm abbrs Active Kitty or WezTerm session
(:w, :wv, :wh, :t, etc.)
Done desktop notifications Graphical desktop with a notification daemon
spwin Kitty or WezTerm
@@ -2966,17 +2960,19 @@ __fish_config_op_integrations disables all of them.
upgrade paru or yay (Arch Linux only)
WakaTime hook wakatime CLI and a configured API key
Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print
Disabled integration commands (`spwin`, `tab`, `split`, `hist`, `logs`, `upgrade`) print
a colored error to stderr naming the variable that disabled them rather than
silently failing.
## C5 — Logging and Capture
Five components capture shell output to disk. Unlike every other category,
C5 is opt-in: it stays off until __fish_config_op_logging is set to an
C5 is opt-in: it stays off until `__fish_config_op_logging` is set to an
explicit truthy value, and a truthy master switch does not enable it. While
it is off, all capture is skipped and the logging wrappers are removed.
CAUTION: This configuration is capable of silently recording terminal output and secrets directly to disk. See below for details on how this capture mechanism works, where files are stored, and how to manage its state.
# Turn it on (persistently, in every shell):
set -U __fish_config_op_logging on
@@ -2986,38 +2982,38 @@ it is off, all capture is skipped and the logging wrappers are removed.
Component What it captures
───────────────────────────────────────────────────────────────────────────
Scrollback capture Terminal session output saved to:
~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log`
tmux pane capture Continuous pane stream via pipe-pane, saved to:
~/.terminal_history/tmux_<session>-w<win>-p<pane>_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/tmux_<session>-w<win>-p<pane>_YYYY-MM-DD_HH-MM-SS.log`
zellij pane capture Pane scrollback snapshot on shell exit, saved to:
~/.terminal_history/zellij_<session>-p<pane>_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/zellij_<session>-p<pane>_YYYY-MM-DD_HH-MM-SS.log`
paru wrapper All paru/AUR output captured to:
~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log`
yay wrapper All yay/AUR output captured to:
~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
Kitty watcher watcher.py captures scrollback when Kitty closes
`~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log`
Kitty watcher `watcher.py` captures scrollback when Kitty closes
NOTE: **Turning off logging does not delete any existing logs.**
They remain in `$SCROLLBACK_HISTORY_DIR` (defaults to: `~/.terminal_history/`)
until you remove them manually.
The tmux capture starts automatically when fish launches inside any tmux
pane ($TMUX is set). It uses tmux's native pipe-pane to stream all pane
pane (`$TMUX` is set). It uses tmux's native pipe-pane to stream all pane
output directly to disk without an intermediate process. Each fish shell
session gets its own log file; a new log is created on each shell start
(including exec fish and new splits). Before each new log, the oldest
tmux_*.log files are pruned (by modification time) to keep the total within
SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour.
`tmux_*.log` files are pruned (by modification time) to keep the total within
`SCROLLBACK_HISTORY_MAX_FILES`, matching the paru/yay wrapper behaviour.
The zellij capture works differently: Zellij has no live output-streaming
facility like pipe-pane, so the log is taken as a one-shot snapshot when the
shell exits, via `zellij action dump-screen --full --ansi` (the --ansi flag
shell exits, via `zellij action dump-screen --full --ansi` (the `--ansi` flag
preserves color). The dump is captured on the fish process's stdout and
written to the log file by fish itself (not via `--path`, which would make the
zellij server write the file). A fish_exit handler (registered whenever
$ZELLIJ is set) writes the pane's full scrollback and then prunes old
zellij_*.log files the same way. Because the capture happens at exit, toggling
__fish_config_op_logging takes effect on the next exit with no restart or
`$ZELLIJ` is set) writes the pane's full scrollback and then prunes old
`zellij_*.log` files the same way. Because the capture happens at exit, toggling
`__fish_config_op_logging` takes effect on the next exit with no restart or
sentinel coordination needed — the C5 guard is re-checked when the handler
fires.
@@ -3039,12 +3035,12 @@ logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane
or quit actions.
The Kitty watcher is managed by the kitty-logging command: it symlinks the
watcher (fish-config-watcher.py) into the Kitty config directory and wires it
into kitty.conf via a managed block. Inside Kitty, a non-blocking
watcher (`fish-config-watcher.py`) into the Kitty config directory and wires it
into `kitty.conf` via a managed block. Inside Kitty, a non-blocking
per-session reminder points first-time users at `kitty-logging install` until
they install or run `kitty-logging dismiss`; the reminder is itself gated on
C5, so it stays silent until you enable logging. Install affects new Kitty
windows only; runtime disable is still handled by the .logging_disabled
windows only; runtime disable is still handled by the `.logging_disabled`
sentinel.
Logging coordination via sentinel file
@@ -3055,26 +3051,26 @@ out-of-process components (the Kitty watcher and all running shells):
~/.config/fish/.logging_disabled
Because C5 is off by default, the sentinel is present on a fresh install —
the startup sync in conf.d/logging-events.fish reconciles it on every shell
the startup sync in `conf.d/logging-events.fish` reconciles it on every shell
start, so it appears without any action on your part.
Disabling __fish_config_op_logging (or leaving it unset):
Disabling `__fish_config_op_logging` (or leaving it unset):
1. Creates the sentinel immediately in every open shell.
2. Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
bare /usr/bin/paru and /usr/bin/yay are used instead.
3. Kitty's watcher.py reads the sentinel on each save attempt and
2. Removes `~/.local/bin/paru` and `~/.local/bin/yay` logging wrappers;
bare `/usr/bin/paru` and `/usr/bin/yay` are used instead.
3. Kitty's `watcher.py` reads the sentinel on each save attempt and
skips capture — no Kitty restart required.
4. smart_exit stops saving scrollback logs.
5. Stops tmux pipe-pane capture in every open fish shell inside tmux.
5. Stops `tmux pipe-pane` capture in every open fish shell inside tmux.
Enabling __fish_config_op_logging:
Enabling `__fish_config_op_logging`:
1. Removes the sentinel in every open shell.
2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
2. Regenerates paru/yay logging wrappers in `~/.local/bin/`.
3. Kitty watcher resumes capture on the next session exit.
4. Restarts tmux pipe-pane capture in every open fish shell inside tmux.
Changes propagate to all running shells through an event handler that fires
whenever __fish_config_op_logging changes — no shell restart needed.
whenever `__fish_config_op_logging` changes — no shell restart needed.
Note: C3 and C5 compose independently. C3 controls whether the smart_exit
wrapper is active at all; C5 controls only the scrollback-capture block
@@ -3097,7 +3093,7 @@ not override it.
Fisher is bootstrapped automatically on the **first interactive session** via
`conf.d/first_run.fish`. This also applies the Catppuccin Mocha theme and
prints a one-time welcome message (gated by __fish_config_op_greeting; set
prints a one-time welcome message (gated by `__fish_config_op_greeting`; set
it to 0 to suppress). Subsequent sessions skip all first-run logic with zero
overhead.
@@ -3487,12 +3483,12 @@ This configuration groups its opinionated behaviors into six categories (C1–C6
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)
C1 | Command Shadows | Wraps destructive commands (`rm`, `cp`) to be safe by default |
C2 | Startup Side-Effects | Bootstraps Fisher, generates wrappers, auto-activates venvs |
C3 | Overrides | Overrides `cd`, sets Vi mode, binds `<CR>` to `smart_enter` |
C4 | Integrations | Kitty/Wezterm integrations, starship hooks, fzf theme |
C5 | Logging and Capture | Session logs, command duration |
C6 | Greeting & First-Run UI | Custom startup banner |
Disable all opinionated features at once (Minimal Mode):
docs/manual/01-configuration-variables.md
+1 -1
View File
@@ -20,7 +20,7 @@ Override them in local.fish (see Section 10, Personalization).
| `XDG_DATA_HOME` | `~/.local/share` |
| `XDG_STATE_HOME` | `~/.local/state` |
Tools that respect XDG are directed to these paths rather than polluting $HOME.
Tools that respect XDG are directed to these paths rather than polluting `$HOME`.
## Tool Homes (XDG-compliant)
docs/manual/04-abbreviations.md
+1 -1
View File
@@ -43,7 +43,7 @@ some expand differently in Kitty vs WezTerm vs other terminals.
These abbreviations control the terminal emulator. Each has a Kitty
variant and a WezTerm variant; the correct one is inserted based on
$TERM or $TERM_PROGRAM.
`$TERM` or `$TERM_PROGRAM`.
:w New OS window
:wv Split pane horizontally (new pane below)
docs/manual/07-customization.md
+212
View File
@@ -0,0 +1,212 @@
---
title: Customization
manTitle: 7. CUSTOMIZATION
sidebar:
order: 11
helpKeywords:
- customization
- customize
---
This section explains how to adapt the configuration to your specific workflow, including local machine overrides and opinionated component toggles.
## Machine-local Configuration
Place machine-specific settings that should not be committed to git in:
$__fish_user_dots_path/local.fish
`__fish_user_dots_path` defaults to `~/.config/.user-dots/fish`. Set a
custom location with:
set -U __fish_user_dots_path /path/to/your/dots/fish
Typical uses: additional PATH entries, local aliases, hostname-specific env
vars, work-specific tool configs.
For convenience, a git-ignored `user-dots` symlink in the fish config
directory tracks `$__fish_user_dots_path` so the overlay can be browsed from
`~/.config/fish/`. It is created if missing and repointed if the path changes.
Opt out by setting `__fish_user_dots_symlink` to a falsy value, or toggling
"Dots link" off on the config-settings Paths page — this stops generation and
removes any existing link. It only ever manages a symlink and never clobbers a
real file or directory at that path.
## Secrets and API Keys
$__fish_user_dots_path/secrets.fish
Store API tokens, GPG keys, private credentials here. This file is never
committed. It is sourced by local.fish directly, not by config.fish.
`local.fish` is sourced at the end of config.fish on every interactive
session, so it and its companion secrets.fish can override anything set
earlier.
## Overriding Configuration Variables
Any variable set in local.fish after the main config loads takes effect.
Example: to increase the scrollback history limit:
# in local.fish
set -gx SCROLLBACK_HISTORY_MAX_FILES 200
## Fish Universal Variables
Some settings (fzf colors, theme) are stored in fish_variables via
`set -U`. These are machine-local and git-ignored. Do not commit
fish_variables.
## Opinionated Components (Minimal Mode)
Every opinionated piece of this config is active by default but can be
switched off through six category opt-out variables, each evaluated via
`__fish_variable_check`. Set a variable to any falsy value (0, false, no,
off, n) to disable its category; erase it or set a truthy value (1, true,
yes, on, y) to re-enable. Unset means enabled — except for C5 logging, which
is opt-in (see below).
An explicit per-category truthy value takes precedence over the master
switch: setting `__fish_config_opinionated`=0 disables all unset categories,
but a category with an explicit truthy value remains enabled regardless.
C5 (logging) is the one exception to "unset means enabled". Because it
writes terminal output to disk, it is opt-in: unset means disabled, and the
master switch cannot enable it. Only an explicit truthy value turns logging
on.
Variable Disables
────────────────────────────────────────
__fish_config_op_aliases Command shadows and flag injection:
ls->eza, cat->bat, cd->zoxide,
rm->trash, less->ov, top->btop,
ping->prettyping, ssh->kitten,
du->duf/dust, mkdir/bash wrappers,
history timestamps, grep/cp/mv/wget
flag injection, help intercept, claude
AGENTS.md auto-link
__fish_config_op_autoexec Startup side-effects: Fisher
bootstrap, theme apply, paru/yay
wrapper generation, auto venv
activation, WakaTime hook
__fish_config_op_overrides Key and env overrides: Vi mode,
exit->smart_exit, PAGER/MANPAGER,
CDPATH, bang-bang system, autopair,
puffer, starship prompt, theme
colors, FZF_DEFAULT_OPTS, right
prompt
__fish_config_op_integrations Terminal/tool coupling: Kitty/
WezTerm window abbreviations, done
notifications, spwin/tab/split,
hist, logs, upgrade, WakaTime
__fish_config_op_logging Logging & capture (OPT-IN — this one
is off unless explicitly enabled):
scrollback capture on exit, paru/yay
AUR log wrappers, Kitty watcher
capture; sentinel file coordinates
cross-process state
__fish_config_op_greeting Greeting & first-run UI: per-session
fish_greeting override (defines empty
function late in config.fish to
suppress distro greetings such as
CachyOS fastfetch); first-run welcome
banner in conf.d/first_run.fish
Examples:
# Disable command shadows only (rm becomes plain rm again):
set -U __fish_config_op_aliases off
# Turn session logging on (opt-in; off until you do this):
set -U __fish_config_op_logging on
# Full minimal mode — disable all six categories at once:
set -U __fish_config_opinionated 0
# Re-enable everything (except C5 logging, which stays opt-in):
set -Ue __fish_config_opinionated
# Minimal mode but keep the greeting:
set -U __fish_config_opinionated 0
set -U __fish_config_op_greeting 1
# (erase both to go back to full-flavor defaults)
For an interactive alternative to setting these variables by hand, run
config-settings — a full-screen TUI that flips any category (including C5
logging) on or off, per session or universally. See its entry in Section 5.
NOTE:
- Command shadows (rm, cat, ls, ...) react immediately; conf.d-level components (bindings, prompt, abbreviations, hooks) take effect in new shells.
- With aliases disabled, rm falls back to bare `command rm` — files are deleted permanently, not trashed.
- Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them.
- On CachyOS, the distro fish config's own aliases, history override, and bang-bang bindings are stripped per category as well.
## Prompt and Theme
### Starship
The primary prompt is Starship, initialized by conf.d/starship.fish.
Configure it via ~/.config/starship.toml.
conf.d/starship.fish defines a fish_prompt wrapper that only activates when
starship is in PATH. It emits OSC 133;A (prompt start) immediately before
Starship renders and OSC 133;B (input start) immediately after, placing both
markers on the prompt line itself. This allows ov to use them as sticky
section headers when browsing scrollback logs. Without Starship, fish's
built-in prompt handles these markers automatically.
### Catppuccin Fallback Prompt
When Starship is absent or C3 overrides are disabled, a built-in nim-style
two-line prompt activates from functions/fish_prompt.fish. No external
dependencies — fish builtins only.
Layout:
┬─[user@host:~/path] (main)
╰─>$
Elements:
user Yellow (Catppuccin Yellow); red if root
@host Blue (local) or Teal (SSH)
~/path prompt_pwd abbreviation (Catppuccin Text)
(main) Current git branch in Catppuccin Pink; omitted outside repos
─[V:name] Active Python venv basename; omitted when none
─[N/I/R/V] Vi-mode indicator when vi bindings are active
┬─ / ╰─> Connector lines: Catppuccin Green on success, Red on failure
The right prompt (fish_right_prompt.fish) always renders, regardless of C3
state. On failure it shows a red ✘ and the exit code; on success it shows
only the dim timestamp. When starship is installed and C3 is enabled, the
active Docker context is also shown (if non-default):
✘ 1 󰡨 myctx Fri Jun 12 00:51:21 2026 ← failed, starship+C3 active
✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt
Fri Jun 12 00:51:21 2026 ← success (no ✘)
### FZF
FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in
integrations/fzf.fish. The colors applied:
Background: #1E1E2E (base) #313244 (surface0)
Foreground: #CDD6F4 (text)
Highlights: #F38BA8 (red) #CBA6F7 (mauve) #B4BEFE (lavender)
To customize, override FZF_DEFAULT_OPTS in local.fish.
### Catppuccin Mocha Syntax Highlighting
The Catppuccin Mocha theme ships with this config in themes/ and is applied
on first run via `conf.d/first_run.fish`. Colors are stored in fish_variables
(universal). To switch variants, install a different theme from themes/:
fish_config theme save "Catppuccin Latte"
`---`
docs/manual/07-customization/01-machine-local-configuration.md
-24
View File
@@ -1,24 +0,0 @@
---
title: Machine-local Configuration
---
Place machine-specific settings that should not be committed to git in:
$__fish_user_dots_path/local.fish
`__fish_user_dots_path` defaults to `~/.config/.user-dots/fish`. Set a
custom location with:
set -U __fish_user_dots_path /path/to/your/dots/fish
Typical uses: additional PATH entries, local aliases, hostname-specific env
vars, work-specific tool configs.
For convenience, a git-ignored `user-dots` symlink in the fish config
directory tracks `$__fish_user_dots_path` so the overlay can be browsed from
`~/.config/fish/`. It is created if missing and repointed if the path changes.
Opt out by setting `__fish_user_dots_symlink` to a falsy value, or toggling
"Dots link" off on the config-settings Paths page — this stops generation and
removes any existing link. It only ever manages a symlink and never clobbers a
real file or directory at that path.
docs/manual/07-customization/02-secrets-and-api-keys.md
-13
View File
@@ -1,13 +0,0 @@
---
title: Secrets and API Keys
---
$__fish_user_dots_path/secrets.fish
Store API tokens, GPG keys, private credentials here. This file is never
committed. It is sourced by local.fish directly, not by config.fish.
`local.fish` is sourced at the end of config.fish on every interactive
session, so it and its companion secrets.fish can override anything set
earlier.
docs/manual/07-customization/03-overriding-configuration-variables.md
-10
View File
@@ -1,10 +0,0 @@
---
title: Overriding Configuration Variables
---
Any variable set in local.fish after the main config loads takes effect.
Example: to increase the scrollback history limit:
# in local.fish
set -gx SCROLLBACK_HISTORY_MAX_FILES 200
docs/manual/07-customization/04-fish-universal-variables.md
-8
View File
@@ -1,8 +0,0 @@
---
title: Fish Universal Variables
---
Some settings (fzf colors, theme) are stored in fish_variables via
`set -U`. These are machine-local and git-ignored. Do not commit
fish_variables.
docs/manual/07-customization/05-opinionated-components-minimal-mode.md
-86
View File
@@ -1,86 +0,0 @@
---
title: Opinionated Components (Minimal Mode)
---
Every opinionated piece of this config is active by default but can be
switched off through six category opt-out variables, each evaluated via
__fish_variable_check. Set a variable to any falsy value (0, false, no,
off, n) to disable its category; erase it or set a truthy value (1, true,
yes, on, y) to re-enable. Unset means enabled — except for C5 logging, which
is opt-in (see below).
An explicit per-category truthy value takes precedence over the master
switch: setting __fish_config_opinionated=0 disables all unset categories,
but a category with an explicit truthy value remains enabled regardless.
C5 (logging) is the one exception to "unset means enabled". Because it
writes terminal output to disk, it is opt-in: unset means disabled, and the
master switch cannot enable it. Only an explicit truthy value turns logging
on.
Variable Disables
────────────────────────────────────────
__fish_config_op_aliases Command shadows and flag injection:
ls->eza, cat->bat, cd->zoxide,
rm->trash, less->ov, top->btop,
ping->prettyping, ssh->kitten,
du->duf/dust, mkdir/bash wrappers,
history timestamps, grep/cp/mv/wget
flag injection, help intercept, claude
AGENTS.md auto-link
__fish_config_op_autoexec Startup side-effects: Fisher
bootstrap, theme apply, paru/yay
wrapper generation, auto venv
activation, WakaTime hook
__fish_config_op_overrides Key and env overrides: Vi mode,
exit->smart_exit, PAGER/MANPAGER,
CDPATH, bang-bang system, autopair,
puffer, starship prompt, theme
colors, FZF_DEFAULT_OPTS, right
prompt
__fish_config_op_integrations Terminal/tool coupling: Kitty/
WezTerm window abbreviations, done
notifications, spwin/tab/split,
hist, logs, upgrade, WakaTime
__fish_config_op_logging Logging & capture (OPT-IN — this one
is off unless explicitly enabled):
scrollback capture on exit, paru/yay
AUR log wrappers, Kitty watcher
capture; sentinel file coordinates
cross-process state
__fish_config_op_greeting Greeting & first-run UI: per-session
fish_greeting override (defines empty
function late in config.fish to
suppress distro greetings such as
CachyOS fastfetch); first-run welcome
banner in conf.d/first_run.fish
Examples:
# Disable command shadows only (rm becomes plain rm again):
set -U __fish_config_op_aliases off
# Turn session logging on (opt-in; off until you do this):
set -U __fish_config_op_logging on
# Full minimal mode — disable all six categories at once:
set -U __fish_config_opinionated 0
# Re-enable everything (except C5 logging, which stays opt-in):
set -Ue __fish_config_opinionated
# Minimal mode but keep the greeting:
set -U __fish_config_opinionated 0
set -U __fish_config_op_greeting 1
# (erase both to go back to full-flavor defaults)
For an interactive alternative to setting these variables by hand, run
config-settings — a full-screen TUI that flips any category (including C5
logging) on or off, per session or universally. See its entry in Section 5.
NOTE:
- Command shadows (rm, cat, ls, ...) react immediately; conf.d-level components (bindings, prompt, abbreviations, hooks) take effect in new shells.
- With aliases disabled, rm falls back to bare `command rm` — files are deleted permanently, not trashed.
- Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print an error naming the variable that disabled them.
- On CachyOS, the distro fish config's own aliases, history override, and bang-bang bindings are stripped per category as well.
docs/manual/07-customization/06-prompt-and-theme.md
-66
View File
@@ -1,66 +0,0 @@
---
title: Prompt and Theme
---
### Starship
The primary prompt is Starship, initialized by conf.d/starship.fish.
Configure it via ~/.config/starship.toml.
conf.d/starship.fish defines a fish_prompt wrapper that only activates when
starship is in PATH. It emits OSC 133;A (prompt start) immediately before
Starship renders and OSC 133;B (input start) immediately after, placing both
markers on the prompt line itself. This allows ov to use them as sticky
section headers when browsing scrollback logs. Without Starship, fish's
built-in prompt handles these markers automatically.
### Catppuccin Fallback Prompt
When Starship is absent or C3 overrides are disabled, a built-in nim-style
two-line prompt activates from functions/fish_prompt.fish. No external
dependencies — fish builtins only.
Layout:
┬─[user@host:~/path] (main)
╰─>$
Elements:
user Yellow (Catppuccin Yellow); red if root
@host Blue (local) or Teal (SSH)
~/path prompt_pwd abbreviation (Catppuccin Text)
(main) Current git branch in Catppuccin Pink; omitted outside repos
─[V:name] Active Python venv basename; omitted when none
─[N/I/R/V] Vi-mode indicator when vi bindings are active
┬─ / ╰─> Connector lines: Catppuccin Green on success, Red on failure
The right prompt (fish_right_prompt.fish) always renders, regardless of C3
state. On failure it shows a red ✘ and the exit code; on success it shows
only the dim timestamp. When starship is installed and C3 is enabled, the
active Docker context is also shown (if non-default):
✘ 1 󰡨 myctx Fri Jun 12 00:51:21 2026 ← failed, starship+C3 active
✘ 1 Fri Jun 12 00:51:21 2026 ← failed, fallback prompt
Fri Jun 12 00:51:21 2026 ← success (no ✘)
### FZF
FZF is themed to Catppuccin Mocha via FZF_DEFAULT_OPTS set in
integrations/fzf.fish. The colors applied:
Background: #1E1E2E (base) #313244 (surface0)
Foreground: #CDD6F4 (text)
Highlights: #F38BA8 (red) #CBA6F7 (mauve) #B4BEFE (lavender)
To customize, override FZF_DEFAULT_OPTS in local.fish.
### Catppuccin Mocha Syntax Highlighting
The Catppuccin Mocha theme ships with this config in themes/ and is applied
on first run via `conf.d/first_run.fish`. Colors are stored in fish_variables
(universal). To switch variants, install a different theme from themes/:
fish_config theme save "Catppuccin Latte"
---
docs/manual/07-customization/index.md
-11
View File
@@ -1,11 +0,0 @@
---
title: Customization
manTitle: 7. CUSTOMIZATION
sidebar:
order: 11
helpKeywords:
- customization
- customize
---
This section explains how to adapt the configuration to your specific workflow, including local machine overrides and opinionated component toggles.
docs/manual/08-components-reference/01-c1-command-shadows.md
+1 -1
View File
@@ -2,7 +2,7 @@
title: C1 — Command Shadows
---
Disabling __fish_config_op_aliases restores standard system behavior for
Disabling `__fish_config_op_aliases` restores standard system behavior for
all of these commands.
Command / Alias Active behavior Disabled fallback
docs/manual/08-components-reference/02-c2-startup-side-effects.md
+6 -6
View File
@@ -3,7 +3,7 @@ title: C2 — Startup Side-Effects
---
These run automatically without any user action. Disabling
__fish_config_op_autoexec prevents all of them.
`__fish_config_op_autoexec` prevents all of them.
Component Trigger What it does
───────────────────────────────────────────────────────────────────────────
@@ -23,15 +23,15 @@ wrapper generation, no automatic venv activation, no WakaTime reporting,
no auto-pull (the PWD handler is never registered), and the user-dots
convenience symlink is not created. The symlink is git-ignored and only ever
managed as a symlink — a real file or directory at that path is left untouched.
The symlink has its own opt-out independent of C2: set __fish_user_dots_symlink
The symlink has its own opt-out independent of C2: set `__fish_user_dots_symlink`
to a falsy value (or toggle "Dots link" off on the config-settings Paths page)
to stop generating it and remove any existing link — honoured even when C2 is
enabled. Managed by the __fish_user_dots_link helper.
The first-run completion marker (__fish_config_first_run_complete) is still
enabled. Managed by the `__fish_user_dots_link` helper.
The first-run completion marker (`__fish_config_first_run_complete`) is still
set so the init does not re-run on subsequent shells.
Python venv activation fires on every directory change. If a directory uses
direnv (.envrc present), direnv takes priority and auto-venv is skipped for
direnv (`.envrc` present), direnv takes priority and auto-venv is skipped for
that directory.
Auto-pull fast-forwards opted-in repositories in the background when you cd
@@ -40,6 +40,6 @@ the `auto-pull` command (see its entry in the functions reference). It only
ever fast-forwards a clean repo whose branch has an upstream — never rebases,
merges, or overwrites work — so it is a no-op on dirty trees, divergent
branches, or repos without a remote. The handler fires once per repo entry
(not on every sub-directory cd). The registry is machine-local at
(not on every sub-directory `cd`). The registry is machine-local at
`$__fish_user_dots_path/auto-pull.list` (defaults to `~/.config/.user-dots/fish/auto-pull.list`) and is never committed.
docs/manual/08-components-reference/03-c3-key-and-environment-overrides.md
+3 -3
View File
@@ -3,7 +3,7 @@ title: C3 — Key and Environment Overrides
---
These change fundamental shell behavior: how keys work, which pager opens,
and what the prompt looks like. Disabling __fish_config_op_overrides removes
and what the prompt looks like. Disabling `__fish_config_op_overrides` removes
all of them.
Override What it replaces or sets
@@ -25,8 +25,8 @@ all of them.
FZF_DEFAULT_OPTS FZF themed to Catppuccin Mocha colors
Right prompt fish_right_prompt: exit code (on failure) + dim timestamp; always rendered; Docker context added when starship+C3 active
The bang-bang system spans key_bindings.fish, abbr.fish, puffer.fish, and
six expand_bang_*.fish functions. All are gated together — disabling C3
The bang-bang system spans `key_bindings.fish`, `abbr.fish`, `puffer.fish`, and
six `expand_bang_*.fish` functions. All are gated together — disabling C3
removes the entire bang-expansion system at once.
When C3 is disabled, `exit` falls back to `builtin exit` with no scrollback
docs/manual/08-components-reference/04-c4-terminal-and-tool-integration.md
+3 -3
View File
@@ -3,11 +3,11 @@ title: C4 — Terminal and Tool Integration
---
These features couple the shell to specific external tools. Disabling
__fish_config_op_integrations disables all of them.
`__fish_config_op_integrations` disables all of them.
Component Requires
───────────────────────────────────────────────────────────────────────────
~60 Kitty/WezTerm abbrs Active Kitty or WezTerm session
≈ 60 Kitty/WezTerm abbrs Active Kitty or WezTerm session
(:w, :wv, :wh, :t, etc.)
Done desktop notifications Graphical desktop with a notification daemon
spwin Kitty or WezTerm
@@ -18,7 +18,7 @@ __fish_config_op_integrations disables all of them.
upgrade paru or yay (Arch Linux only)
WakaTime hook wakatime CLI and a configured API key
Disabled integration commands (spwin, tab, split, hist, logs, upgrade) print
Disabled integration commands (`spwin`, `tab`, `split`, `hist`, `logs`, `upgrade`) print
a colored error to stderr naming the variable that disabled them rather than
silently failing.
docs/manual/08-components-reference/05-c5-logging-and-capture.md
+28 -26
View File
@@ -3,10 +3,12 @@ title: C5 — Logging and Capture
---
Five components capture shell output to disk. Unlike every other category,
C5 is opt-in: it stays off until __fish_config_op_logging is set to an
C5 is opt-in: it stays off until `__fish_config_op_logging` is set to an
explicit truthy value, and a truthy master switch does not enable it. While
it is off, all capture is skipped and the logging wrappers are removed.
CAUTION: This configuration is capable of silently recording terminal output and secrets directly to disk. See below for details on how this capture mechanism works, where files are stored, and how to manage its state.
# Turn it on (persistently, in every shell):
set -U __fish_config_op_logging on
@@ -16,38 +18,38 @@ it is off, all capture is skipped and the logging wrappers are removed.
Component What it captures
───────────────────────────────────────────────────────────────────────────
Scrollback capture Terminal session output saved to:
~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/scrollback_YYYY-MM-DD_HH-MM-SS.log`
tmux pane capture Continuous pane stream via pipe-pane, saved to:
~/.terminal_history/tmux_<session>-w<win>-p<pane>_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/tmux_<session>-w<win>-p<pane>_YYYY-MM-DD_HH-MM-SS.log`
zellij pane capture Pane scrollback snapshot on shell exit, saved to:
~/.terminal_history/zellij_<session>-p<pane>_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/zellij_<session>-p<pane>_YYYY-MM-DD_HH-MM-SS.log`
paru wrapper All paru/AUR output captured to:
~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log
`~/.terminal_history/paru_YYYY-MM-DD_HH-MM-SS.log`
yay wrapper All yay/AUR output captured to:
~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log
Kitty watcher watcher.py captures scrollback when Kitty closes
`~/.terminal_history/yay_YYYY-MM-DD_HH-MM-SS.log`
Kitty watcher `watcher.py` captures scrollback when Kitty closes
NOTE: **Turning off logging does not delete any existing logs.**
They remain in `$SCROLLBACK_HISTORY_DIR` (defaults to: `~/.terminal_history/`)
until you remove them manually.
The tmux capture starts automatically when fish launches inside any tmux
pane ($TMUX is set). It uses tmux's native pipe-pane to stream all pane
pane (`$TMUX` is set). It uses tmux's native pipe-pane to stream all pane
output directly to disk without an intermediate process. Each fish shell
session gets its own log file; a new log is created on each shell start
(including exec fish and new splits). Before each new log, the oldest
tmux_*.log files are pruned (by modification time) to keep the total within
SCROLLBACK_HISTORY_MAX_FILES, matching the paru/yay wrapper behaviour.
`tmux_*.log` files are pruned (by modification time) to keep the total within
`SCROLLBACK_HISTORY_MAX_FILES`, matching the paru/yay wrapper behaviour.
The zellij capture works differently: Zellij has no live output-streaming
facility like pipe-pane, so the log is taken as a one-shot snapshot when the
shell exits, via `zellij action dump-screen --full --ansi` (the --ansi flag
shell exits, via `zellij action dump-screen --full --ansi` (the `--ansi` flag
preserves color). The dump is captured on the fish process's stdout and
written to the log file by fish itself (not via `--path`, which would make the
zellij server write the file). A fish_exit handler (registered whenever
$ZELLIJ is set) writes the pane's full scrollback and then prunes old
zellij_*.log files the same way. Because the capture happens at exit, toggling
__fish_config_op_logging takes effect on the next exit with no restart or
`$ZELLIJ` is set) writes the pane's full scrollback and then prunes old
`zellij_*.log` files the same way. Because the capture happens at exit, toggling
`__fish_config_op_logging` takes effect on the next exit with no restart or
sentinel coordination needed — the C5 guard is re-checked when the handler
fires.
@@ -69,12 +71,12 @@ logged, end the session with `exit` or Ctrl-D rather than zellij's close-pane
or quit actions.
The Kitty watcher is managed by the kitty-logging command: it symlinks the
watcher (fish-config-watcher.py) into the Kitty config directory and wires it
into kitty.conf via a managed block. Inside Kitty, a non-blocking
watcher (`fish-config-watcher.py`) into the Kitty config directory and wires it
into `kitty.conf` via a managed block. Inside Kitty, a non-blocking
per-session reminder points first-time users at `kitty-logging install` until
they install or run `kitty-logging dismiss`; the reminder is itself gated on
C5, so it stays silent until you enable logging. Install affects new Kitty
windows only; runtime disable is still handled by the .logging_disabled
windows only; runtime disable is still handled by the `.logging_disabled`
sentinel.
Logging coordination via sentinel file
@@ -85,26 +87,26 @@ out-of-process components (the Kitty watcher and all running shells):
~/.config/fish/.logging_disabled
Because C5 is off by default, the sentinel is present on a fresh install —
the startup sync in conf.d/logging-events.fish reconciles it on every shell
the startup sync in `conf.d/logging-events.fish` reconciles it on every shell
start, so it appears without any action on your part.
Disabling __fish_config_op_logging (or leaving it unset):
Disabling `__fish_config_op_logging` (or leaving it unset):
1. Creates the sentinel immediately in every open shell.
2. Removes ~/.local/bin/paru and ~/.local/bin/yay logging wrappers;
bare /usr/bin/paru and /usr/bin/yay are used instead.
3. Kitty's watcher.py reads the sentinel on each save attempt and
2. Removes `~/.local/bin/paru` and `~/.local/bin/yay` logging wrappers;
bare `/usr/bin/paru` and `/usr/bin/yay` are used instead.
3. Kitty's `watcher.py` reads the sentinel on each save attempt and
skips capture — no Kitty restart required.
4. smart_exit stops saving scrollback logs.
5. Stops tmux pipe-pane capture in every open fish shell inside tmux.
5. Stops `tmux pipe-pane` capture in every open fish shell inside tmux.
Enabling __fish_config_op_logging:
Enabling `__fish_config_op_logging`:
1. Removes the sentinel in every open shell.
2. Regenerates paru/yay logging wrappers in ~/.local/bin/.
2. Regenerates paru/yay logging wrappers in `~/.local/bin/`.
3. Kitty watcher resumes capture on the next session exit.
4. Restarts tmux pipe-pane capture in every open fish shell inside tmux.
Changes propagate to all running shells through an event handler that fires
whenever __fish_config_op_logging changes — no shell restart needed.
whenever `__fish_config_op_logging` changes — no shell restart needed.
Note: C3 and C5 compose independently. C3 controls whether the smart_exit
wrapper is active at all; C5 controls only the scrollback-capture block
docs/manual/09-fisher-plugins.md
+1 -1
View File
@@ -10,7 +10,7 @@ helpKeywords:
Fisher is bootstrapped automatically on the **first interactive session** via
`conf.d/first_run.fish`. This also applies the Catppuccin Mocha theme and
prints a one-time welcome message (gated by __fish_config_op_greeting; set
prints a one-time welcome message (gated by `__fish_config_op_greeting`; set
it to 0 to suppress). Subsequent sessions skip all first-run logic with zero
overhead.
docs/manual/12-troubleshooting.md
+12 -12
View File
@@ -94,7 +94,7 @@ returns you to the default off state:
This takes effect immediately in all running shells — no restart needed. The
sentinel file, wrapper removal, and pipe-pane teardown happen automatically.
See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full component breakdown.
See [C5 — Logging and Capture](/08-components-reference/05-c5-logging-and-capture/) for the full component breakdown.
## Change or Disable the Greeting
@@ -115,7 +115,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](/08-components-reference/06-c6-greeting-and-first-run-ui/) for details.
## Secrets and Machine-Local Configuration
@@ -139,7 +139,7 @@ Disable it with:
set -U __fish_user_dots_symlink false
See [Personalization](/10-personalization/) for the full `local.fish` / `secrets.fish`
See [Personalization](/11-personalization/) for the full `local.fish` / `secrets.fish`
layout.
## Tool Init Does Nothing (Return Sentinel)
@@ -156,7 +156,7 @@ Fix: create a dedicated `conf.d/` file instead of appending to `config.fish`:
mytool init fish | source
All existing integrations (starship, zoxide, direnv) already have `conf.d/`
files. See [Return Sentinel](/09-installation/#return-sentinel) for background.
files. See [Return Sentinel](/10-installation/#return-sentinel) for background.
## Missing Dependencies
@@ -186,7 +186,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` (See [Personalization](/10-personalization/)):
override it in `local.fish` (See [Personalization](/11-personalization/)):
# $__fish_user_dots_path/local.fish
fish_default_key_bindings
@@ -199,7 +199,7 @@ 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](/08-components-reference/03-c3-key-and-environment-overrides/) for the full list of
what C3 controls.
## What's with the C1-C6 stuff?
@@ -208,12 +208,12 @@ This configuration groups its opinionated behaviors into six categories (C1–C6
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)
C1 | [Command Shadows](/08-components-reference/01-c1-command-shadows/) | Wraps destructive commands (`rm`, `cp`) to be safe by default |
C2 | [Startup Side-Effects](/08-components-reference/02-c2-startup-side-effects/) | Bootstraps Fisher, generates wrappers, auto-activates venvs |
C3 | [Overrides](/08-components-reference/03-c3-key-and-environment-overrides/) | Overrides `cd`, sets Vi mode, binds `<CR>` to `smart_enter` |
C4 | [Integrations](/08-components-reference/04-c4-terminal-and-tool-integration/) | Kitty/Wezterm integrations, starship hooks, fzf theme |
C5 | [Logging and Capture](/08-components-reference/05-c5-logging-and-capture/) | Session logs, command duration |
C6 | [Greeting & First-Run UI](/08-components-reference/06-c6-greeting-and-first-run-ui/) | Custom startup banner |
Disable all opinionated features at once (Minimal Mode):
docs/manual/404.md
+3 -3
View File
@@ -10,7 +10,7 @@ hero:
<CardGrid>
<LinkCard title="Home" description="Return to the main manual page" href="/" />
<LinkCard title="Installation" description="Set up the configuration" href="/09-installation/" />
<LinkCard title="Troubleshooting" description="Fix common issues" href="/11-troubleshooting/" />
<LinkCard title="Function Reference" description="Browse all functions" href="/05-functions/" />
<LinkCard title="Installation" description="Set up the configuration" href="/10-installation/" />
<LinkCard title="Troubleshooting" description="Fix common issues" href="/12-troubleshooting/" />
<LinkCard title="Function Reference" description="Browse all functions" href="/reference/" />
</CardGrid>
docs/manual/index.md
+4 -16
View File
@@ -14,30 +14,18 @@ helpKeywords:
A production-grade Fish shell configuration targeting Fish 4.x. It provides:
- Drop-in replacements for common Unix tools (ls, cat, rm, du, ping, less)
- Drop-in replacements for common Unix tools (`ls`, `cat`, `rm`, `du`, `ping`, `less`)
- Deep Kitty and WezTerm terminal integration: tab/window/pane management from
the command line
- Optional session logging: terminal scrollback, tmux/zellij panes, and
paru/yay output captured to ~/.terminal_history (off by default; see below)
paru/yay output captured to `~/.terminal_history` (off by default; see [C5 Logging](/08-components-reference/05-c5-logging-and-capture/))
- Automatic Python virtualenv activation on directory change
- Cross-platform package management via pkg and fish-deps
- AI scaffolding helpers for Claude Code and Antigravity
- Catppuccin Mocha color theme throughout
<LinkButton href="/09-installation/">Install now</LinkButton>
<LinkButton href="/reference/" variant="secondary">Function reference</LinkButton>
CAUTION: **SESSION LOGGING**
If enabled, this configuration can silently record terminal output to
`~/.terminal_history`: Kitty scrollback on window close, live tmux pane
streams, zellij pane snapshots on exit, and full paru/yay output. These logs
can contain command output, file contents, and secrets printed to the
terminal. Nothing leaves your machine, but the files persist locally. Logging
is off unless you turn it on.
- Enable all logging with: `set -U __fish_config_op_logging on`
- Prefer a menu? Run the interactive picker: `config-settings`
- Turn it back off with: `set -U __fish_config_op_logging off` (or erase the variable)
- See [C5 — Logging and Capture](/07-customization/#c5-logging-and-capture) for the full breakdown.
<LinkButton href="/10-installation/" icon="cloud-download" style="font-size: 1.25rem; padding: 1rem 1.5rem; margin-right: 1rem;">Install now</LinkButton>
<LinkButton href="/reference/" variant="secondary" style="font-size: 1.125rem; padding: 0.85rem 1.25rem;">Function reference</LinkButton>
The configuration uses a structured file tree:
docs/site/astro.config.mjs
+9 -1
View File
@@ -1,5 +1,7 @@
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightLinksValidator from 'starlight-links-validator';
import starlightCatppuccin from '@catppuccin/starlight';
import sidebar from './src/sidebar.json' with { type: 'json' };
export default defineConfig({
@@ -25,7 +27,13 @@ export default defineConfig({
content: 'document.addEventListener("DOMContentLoaded", () => { document.querySelectorAll("starlight-file-tree").forEach(tree => { tree.querySelectorAll("details").forEach((d, i) => { if (i !== 0) d.removeAttribute("open"); }); }); });',
},
],
customCss: ['./src/styles/catppuccin.css'],
plugins: [
starlightLinksValidator(),
starlightCatppuccin({
dark: { flavor: "mocha", accent: "green" },
light: { flavor: "latte", accent: "sky" },
}),
],
expressiveCode: {
// Shiki ships both Catppuccin flavours; Starlight picks by the
// reader's colour scheme, matching the palette in catppuccin.css.
docs/site/package-lock.json
Generated
+159 -1
View File
@@ -9,8 +9,10 @@
"version": "0.0.1",
"dependencies": {
"@astrojs/starlight": "^0.41.4",
"@catppuccin/starlight": "^2.1.0",
"astro": "^7.0.2",
"sharp": "^0.34.5"
"sharp": "^0.34.5",
"starlight-links-validator": "^0.25.2"
}
},
"node_modules/@astrojs/compiler-binding": {
@@ -596,6 +598,19 @@
"node": ">=18"
}
},
"node_modules/@catppuccin/starlight": {
"version": "2.1.0",
"resolved": "https://registry.npmjs.org/@catppuccin/starlight/-/starlight-2.1.0.tgz",
"integrity": "sha512-S5zr0WMHUZgsKzoAebj48DAT5r96jRgJSNftNEIoSi9Nk9KatxP5IUntYqmX5B2L5PGfvKO/oEjINuLLaiRn0g==",
"license": "MIT",
"dependencies": {
"@astrojs/starlight": "^0.41.1"
},
"peerDependencies": {
"@astrojs/starlight": ">=0.38",
"astro": "^6.0.0 || ^7.0.0"
}
},
"node_modules/@clack/core": {
"version": "1.4.3",
"resolved": "https://registry.npmjs.org/@clack/core/-/core-1.4.3.tgz",
@@ -2326,6 +2341,12 @@
"undici-types": "~7.18.0"
}
},
"node_modules/@types/picomatch": {
"version": "4.0.3",
"resolved": "https://registry.npmjs.org/@types/picomatch/-/picomatch-4.0.3.tgz",
"integrity": "sha512-iG0T6+nYJ9FAPmx9SsUlnwcq1ZVRuCXcVEvWnntoPlrOpwtSTKNDC9uVAxTsC3PUvJ+99n4RpAcNgBbHX3JSnQ==",
"license": "MIT"
},
"node_modules/@types/sax": {
"version": "1.2.7",
"resolved": "https://registry.npmjs.org/@types/sax/-/sax-1.2.7.tgz",
@@ -2380,6 +2401,21 @@
"am-i-vibing": "dist/cli.mjs"
}
},
"node_modules/ansi-escapes": {
"version": "7.3.0",
"resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-7.3.0.tgz",
"integrity": "sha512-BvU8nYgGQBxcmMuEeUEmNTvrMVjJNSH7RgW24vXexN4Ven6qCvy4TntnvlnwnMLTVlcRQQdbRY8NKnaIoeWDNg==",
"license": "MIT",
"dependencies": {
"environment": "^1.0.0"
},
"engines": {
"node": ">=18"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/anymatch": {
"version": "3.1.3",
"resolved": "https://registry.npmjs.org/anymatch/-/anymatch-3.1.3.tgz",
@@ -3038,6 +3074,18 @@
"url": "https://github.com/fb55/entities?sponsor=1"
}
},
"node_modules/environment": {
"version": "1.1.0",
"resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz",
"integrity": "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==",
"license": "MIT",
"engines": {
"node": ">=18"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/es-module-lexer": {
"version": "2.3.1",
"resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.1.tgz",
@@ -3367,6 +3415,18 @@
"uncrypto": "^0.1.3"
}
},
"node_modules/has-flag": {
"version": "5.0.1",
"resolved": "https://registry.npmjs.org/has-flag/-/has-flag-5.0.1.tgz",
"integrity": "sha512-CsNUt5x9LUdx6hnk/E2SZLsDyvfqANZSUq4+D3D8RzDJ2M+HDTIkF60ibS1vHaK55vzgiZw1bEPFG9yH7l33wA==",
"license": "MIT",
"engines": {
"node": ">=12"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/hast-util-embedded": {
"version": "3.0.0",
"resolved": "https://registry.npmjs.org/hast-util-embedded/-/hast-util-embedded-3.0.0.tgz",
@@ -3807,6 +3867,18 @@
"url": "https://github.com/sponsors/brc-dd"
}
},
"node_modules/is-absolute-url": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/is-absolute-url/-/is-absolute-url-5.0.0.tgz",
"integrity": "sha512-sdJyNpBnQHuVnBunfzjAecOhZr2+A30ywfFvu3EnxtKLUWfwGgyWUmqHbGZiU6vTfHpCPm5GvLe4BAvlU9n8VQ==",
"license": "MIT",
"engines": {
"node": ">=20"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/is-alphabetical": {
"version": "2.0.1",
"resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz",
@@ -6272,6 +6344,33 @@
"url": "https://github.com/sponsors/wooorm"
}
},
"node_modules/starlight-links-validator": {
"version": "0.25.2",
"resolved": "https://registry.npmjs.org/starlight-links-validator/-/starlight-links-validator-0.25.2.tgz",
"integrity": "sha512-RQiHkM8FHKermsjMkSb+uS/q50Dv5P0O0ECWKxJyTv4stuO8QTorIEKnITDDLEf9/xyg7M69arxiK2ola3OMqA==",
"license": "MIT",
"dependencies": {
"@astrojs/markdown-satteri": "^0.3.2",
"@types/picomatch": "^4.0.2",
"github-slugger": "^2.0.0",
"hast-util-from-html": "^2.0.3",
"is-absolute-url": "^5.0.0",
"mdast-util-mdx-jsx": "^3.2.0",
"mdast-util-to-hast": "^13.2.1",
"picomatch": "^4.0.3",
"satteri": "^0.9.3",
"terminal-link": "^5.0.0",
"unist-util-visit": "^5.1.0",
"yaml": "^2.8.3"
},
"engines": {
"node": ">=22.12.0"
},
"peerDependencies": {
"@astrojs/starlight": ">=0.41.0",
"astro": ">=7.0.2"
}
},
"node_modules/stream-replace-string": {
"version": "2.0.0",
"resolved": "https://registry.npmjs.org/stream-replace-string/-/stream-replace-string-2.0.0.tgz",
@@ -6310,6 +6409,34 @@
"inline-style-parser": "0.2.7"
}
},
"node_modules/supports-color": {
"version": "10.2.2",
"resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz",
"integrity": "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==",
"license": "MIT",
"engines": {
"node": ">=18"
},
"funding": {
"url": "https://github.com/chalk/supports-color?sponsor=1"
}
},
"node_modules/supports-hyperlinks": {
"version": "4.5.0",
"resolved": "https://registry.npmjs.org/supports-hyperlinks/-/supports-hyperlinks-4.5.0.tgz",
"integrity": "sha512-ZW2OvfeCXrNTbLakPUzjQG922EeGCOteFSVoek5DKStTh898wf7zgtuFlzQN8HfZCxC3Eh02yJVrRW51hADf+w==",
"license": "MIT",
"dependencies": {
"has-flag": "^5.0.1",
"supports-color": "^10.2.2"
},
"engines": {
"node": ">=20"
},
"funding": {
"url": "https://github.com/chalk/supports-hyperlinks?sponsor=1"
}
},
"node_modules/svgo": {
"version": "4.0.2",
"resolved": "https://registry.npmjs.org/svgo/-/svgo-4.0.2.tgz",
@@ -6335,6 +6462,22 @@
"url": "https://opencollective.com/svgo"
}
},
"node_modules/terminal-link": {
"version": "5.0.0",
"resolved": "https://registry.npmjs.org/terminal-link/-/terminal-link-5.0.0.tgz",
"integrity": "sha512-qFAy10MTMwjzjU8U16YS4YoZD+NQLHzLssFMNqgravjbvIPNiqkGFR4yjhJfmY9R5OFU7+yHxc6y+uGHkKwLRA==",
"license": "MIT",
"dependencies": {
"ansi-escapes": "^7.0.0",
"supports-hyperlinks": "^4.1.0"
},
"engines": {
"node": ">=20"
},
"funding": {
"url": "https://github.com/sponsors/sindresorhus"
}
},
"node_modules/tiny-inflate": {
"version": "1.0.3",
"resolved": "https://registry.npmjs.org/tiny-inflate/-/tiny-inflate-1.0.3.tgz",
@@ -6860,6 +7003,21 @@
"integrity": "sha512-147y/6YNh+tlp6nd/2pWq38i9h6mz/EuQ6njIrmW8D1BS5nCqs0P6DG+m6zTGnNz5I+uhZ0SHxBs9BsPrwcKDA==",
"license": "MIT"
},
"node_modules/yaml": {
"version": "2.9.0",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
"integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
"license": "ISC",
"bin": {
"yaml": "bin.mjs"
},
"engines": {
"node": ">= 14.6"
},
"funding": {
"url": "https://github.com/sponsors/eemeli"
}
},
"node_modules/yargs-parser": {
"version": "22.0.0",
"resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-22.0.0.tgz",
docs/site/package.json
+4 -2
View File
@@ -11,7 +11,9 @@
},
"dependencies": {
"@astrojs/starlight": "^0.41.4",
"@catppuccin/starlight": "^2.1.0",
"astro": "^7.0.2",
"sharp": "^0.34.5"
"sharp": "^0.34.5",
"starlight-links-validator": "^0.25.2"
}
}
}
docs/site/src/styles/catppuccin.css
-153
View File
@@ -1,153 +0,0 @@
/* Catppuccin Mocha (dark) / Latte (light) mapped onto Starlight tokens. */
:root {
--ctp-rosewater: #f5e0dc;
--ctp-pink: #f5c2e7;
--ctp-mauve: #cba6f7;
--ctp-red: #f38ba8;
--ctp-peach: #fab387;
--ctp-yellow: #f9e2af;
--ctp-green: #a6e3a1;
--ctp-teal: #94e2d5;
--ctp-sky: #89dceb;
--ctp-blue: #89b4fa;
--ctp-lavender: #b4befe;
--ctp-surface: #313244;
--sl-color-accent-low: #1e1e2e;
--sl-color-accent: #89b4fa;
--sl-color-accent-high: #b4befe;
--sl-color-white: #cdd6f4;
--sl-color-gray-1: #bac2de;
--sl-color-gray-2: #a6adc8;
--sl-color-gray-3: #7f849c;
--sl-color-gray-4: #585b70;
--sl-color-gray-5: #45475a;
--sl-color-gray-6: #313244;
--sl-color-black: #181825;
}
:root[data-theme='light'] {
--ctp-rosewater: #dc8a78;
--ctp-pink: #ea76cb;
--ctp-mauve: #8839ef;
--ctp-red: #d20f39;
--ctp-peach: #fe640b;
--ctp-yellow: #df8e1d;
--ctp-green: #40a02b;
--ctp-teal: #179299;
--ctp-sky: #04a5e5;
--ctp-blue: #1e66f5;
--ctp-lavender: #7287fd;
--ctp-surface: #ccd0da;
--sl-color-accent-low: #dce0e8;
--sl-color-accent: #1e66f5;
--sl-color-accent-high: #7287fd;
--sl-color-white: #4c4f69;
--sl-color-gray-1: #5c5f77;
--sl-color-gray-2: #6c6f85;
--sl-color-gray-3: #7c7f93;
--sl-color-gray-4: #9ca0b0;
--sl-color-gray-5: #bcc0cc;
--sl-color-gray-6: #ccd0da;
--sl-color-black: #eff1f5;
}
/* ── Headings ──────────────────────────────────────────────────────── */
/* The manual is one long reference; tinting each level makes the
hierarchy scannable without relying on size alone. */
.sl-markdown-content h1 {
color: var(--ctp-lavender);
}
.sl-markdown-content h2 {
color: var(--ctp-green);
border-bottom: 1px solid var(--sl-color-gray-5);
padding-bottom: 0.2em;
}
.sl-markdown-content h3 {
color: var(--ctp-blue);
}
.sl-markdown-content h4 {
color: var(--ctp-teal);
}
/* ── Inline code ───────────────────────────────────────────────────── */
/* Function names, variables, and flags appear inline constantly; peach
separates them from prose the way the fenced blocks separate examples. */
.sl-markdown-content :not(pre) > code {
color: var(--ctp-peach);
background: var(--ctp-surface);
border: 1px solid var(--sl-color-gray-5);
border-radius: 0.3em;
padding: 0.1em 0.35em;
}
.sl-markdown-content a > code {
color: var(--ctp-sky);
}
/* ── Links ─────────────────────────────────────────────────────────── */
.sl-markdown-content a:not(:where(.not-content *)) {
color: var(--ctp-sky);
text-decoration-color: var(--sl-color-gray-4);
}
.sl-markdown-content a:not(:where(.not-content *)):hover {
color: var(--ctp-teal);
text-decoration-color: currentColor;
}
.sl-link-button.primary {
color: var(--sl-color-black) !important;
}
/* ── Cards ─────────────────────────────────────────────────────────── */
/* Each function category is a grid of LinkCards; a hover accent makes the
grid feel navigable rather than like a wall of boxes. */
.card {
border-color: var(--sl-color-gray-5);
transition:
border-color 150ms ease,
transform 150ms ease;
}
.card:hover {
border-color: var(--ctp-green);
transform: translateY(-2px);
}
.card .title {
color: var(--ctp-lavender);
}
/* ── Asides ────────────────────────────────────────────────────────── */
.starlight-aside--note {
--sl-color-asides-text-accent: var(--ctp-blue);
}
.starlight-aside--tip {
--sl-color-asides-text-accent: var(--ctp-mauve);
}
.starlight-aside--caution {
--sl-color-asides-text-accent: var(--ctp-yellow);
}
.starlight-aside--danger {
--sl-color-asides-text-accent: var(--ctp-red);
}
/* ── Site chrome ───────────────────────────────────────────────────── */
.site-title {
color: var(--ctp-green);
}
/* Table headers carry the accent so the many reference tables in the
manual read as structured data at a glance. */
.sl-markdown-content th {
color: var(--ctp-yellow);
}
docs/verify-manual.py
+4 -4
View File
@@ -690,7 +690,7 @@ def test_customization_notes_render_as_aside():
"""The real 07-customization NOTE paragraph converts to one intact <Aside>."""
import build_manual
path = Path(__file__).parent / "manual" / "07-customization" / "05-opinionated-components-minimal-mode.md"
path = Path(__file__).parent / "manual" / "07-customization.md"
_, body = mt.parse(path)
out = build_manual.prettify(body)
assert out.count('<Aside type="note" title="Note">') >= 1, f"expected at least one Note aside:\n{out}"
@@ -716,7 +716,7 @@ def test_site_promotes_pages_with_asides_or_filetrees_to_mdx():
assert (out / "13-viewing-this-manual.mdx").exists(), "Aside page (NOTE) was not promoted to .mdx"
assert (out / "07-customization/05-opinionated-components-minimal-mode.mdx").exists(), "Aside page (rewritten NOTE) was not promoted to .mdx"
assert (out / "07-customization.mdx").exists(), "Aside page (rewritten NOTE) was not promoted to .mdx"
assert (out / "02-path-setup.mdx").exists(), "Aside page (NOTE) was not promoted to .mdx"
@@ -754,8 +754,8 @@ def test_sidebar_has_no_duplicate_functions_entry():
sidebar = build_manual.build_site(docs / "manual", Path(d))
groups = [e for e in sidebar if "items" in e]
assert len(groups) == 1, f"expected one sidebar group, got {len(groups)}"
group = groups[0]
group = next((g for g in groups if g["label"] == "Functions Reference"), None)
assert group is not None, "expected to find 'Functions Reference' sidebar group"
labels = [item["label"] for item in group["items"]]
assert group["label"] not in labels[1:], (
f"'{group['label']}' is repeated inside its own group: {labels}"