docs: reformat catalog/vars to standard markdown and add intros
Generate documentation / build-docs (push) Successful in 3m16s
Generate documentation / build-docs (push) Successful in 3m16s
Fixed tables and text formatting in the Dependency Catalog and Configuration Variables pages so they render properly as markdown instead of flat code blocks. Added introductory sentences to Troubleshooting and Customization so the Starlight sub-heading navigation cards get injected at the top of the page rather than jumping below the first heading.
This commit is contained in:
@@ -13,130 +13,143 @@ Override them in local.fish (see Section 10, Personalization).
|
||||
|
||||
## Environment Directories (XDG)
|
||||
|
||||
XDG_CONFIG_HOME ~/.config
|
||||
XDG_CACHE_HOME ~/.cache
|
||||
XDG_DATA_HOME ~/.local/share
|
||||
XDG_STATE_HOME ~/.local/state
|
||||
| Variable | Value |
|
||||
|---|---|
|
||||
| `XDG_CONFIG_HOME` | `~/.config` |
|
||||
| `XDG_CACHE_HOME` | `~/.cache` |
|
||||
| `XDG_DATA_HOME` | `~/.local/share` |
|
||||
| `XDG_STATE_HOME` | `~/.local/state` |
|
||||
|
||||
Tools that respect XDG are directed to these paths rather than polluting $HOME.
|
||||
|
||||
## Tool Homes (XDG-compliant)
|
||||
|
||||
CARGO_HOME $XDG_DATA_HOME/cargo
|
||||
RUSTUP_HOME $XDG_DATA_HOME/rustup
|
||||
GOPATH $XDG_DATA_HOME/go
|
||||
BUN_INSTALL $XDG_DATA_HOME/bun
|
||||
NPM_CONFIG_PREFIX $XDG_DATA_HOME/npm-global
|
||||
GNUPGHOME $XDG_CONFIG_HOME/gnupg
|
||||
WAKATIME_HOME $XDG_CONFIG_HOME/wakatime
|
||||
| Variable | Value |
|
||||
|---|---|
|
||||
| `CARGO_HOME` | `$XDG_DATA_HOME/cargo` |
|
||||
| `RUSTUP_HOME` | `$XDG_DATA_HOME/rustup` |
|
||||
| `GOPATH` | `$XDG_DATA_HOME/go` |
|
||||
| `BUN_INSTALL` | `$XDG_DATA_HOME/bun` |
|
||||
| `NPM_CONFIG_PREFIX` | `$XDG_DATA_HOME/npm-global` |
|
||||
| `GNUPGHOME` | `$XDG_CONFIG_HOME/gnupg` |
|
||||
| `WAKATIME_HOME` | `$XDG_CONFIG_HOME/wakatime` |
|
||||
|
||||
## Editor and Pager
|
||||
|
||||
EDITOR nvim (falls back to vi if nvim is absent)
|
||||
VISUAL unset by default; set a GUI editor via local.fish (the edit
|
||||
function falls back to a GUI chain when VISUAL is empty)
|
||||
SUDO_EDITOR same as EDITOR
|
||||
PAGER ov (falls back to less)
|
||||
| Variable | Value / Notes |
|
||||
|---|---|
|
||||
| `EDITOR` | `nvim` (falls back to `vi` if `nvim` is absent) |
|
||||
| `VISUAL` | unset by default; set a GUI editor via `local.fish` (the `edit` function falls back to a GUI chain when `VISUAL` is empty) |
|
||||
| `SUDO_EDITOR` | same as `EDITOR` |
|
||||
| `PAGER` | `ov` (falls back to `less`) |
|
||||
|
||||
## Scrollback History
|
||||
|
||||
__fish_scrollback_history_dir (unset → ~/.terminal_history)
|
||||
__fish_scrollback_history_max_files (unset → 100)
|
||||
SCROLLBACK_HISTORY_DIR ~/.terminal_history (exported mirror)
|
||||
SCROLLBACK_HISTORY_MAX_FILES 100 (exported mirror)
|
||||
| Variable | Value / Notes |
|
||||
|---|---|
|
||||
| `__fish_scrollback_history_dir` | (unset → `~/.terminal_history`) |
|
||||
| `__fish_scrollback_history_max_files` | (unset → `100`) |
|
||||
| `SCROLLBACK_HISTORY_DIR` | `~/.terminal_history` (exported mirror) |
|
||||
| `SCROLLBACK_HISTORY_MAX_FILES` | `100` (exported mirror) |
|
||||
|
||||
The __fish_scrollback_history_* universal variables are the fish-style source
|
||||
The `__fish_scrollback_history_*` universal variables are the fish-style source
|
||||
of truth — set them via `config-settings` → Paths, or `set -U` directly.
|
||||
config.fish exports the SCROLLBACK_HISTORY_* mirrors from them, because the
|
||||
POSIX wrapper scripts (paru/yay/tmux/zellij logging and _prune_terminal_logs)
|
||||
read the exported names from the environment. When the __fish_ vars are unset,
|
||||
the documented defaults are exported. config.fish deliberately does not create
|
||||
`config.fish` exports the `SCROLLBACK_HISTORY_*` mirrors from them, because the
|
||||
POSIX wrapper scripts (`paru`/`yay`/`tmux`/`zellij` logging and `_prune_terminal_logs`)
|
||||
read the exported names from the environment. When the `__fish_` vars are unset,
|
||||
the documented defaults are exported. `config.fish` deliberately does not create
|
||||
a global source var, which would shadow the universal and stop live edits from
|
||||
taking effect.
|
||||
|
||||
Scrollback logs accumulate in SCROLLBACK_HISTORY_DIR as timestamped files.
|
||||
When the count exceeds SCROLLBACK_HISTORY_MAX_FILES the oldest are pruned
|
||||
Scrollback logs accumulate in `SCROLLBACK_HISTORY_DIR` as timestamped files.
|
||||
When the count exceeds `SCROLLBACK_HISTORY_MAX_FILES` the oldest are pruned
|
||||
automatically on exit. Use `logs` to browse them interactively.
|
||||
|
||||
## Other
|
||||
|
||||
GPG_TTY $(tty) — ensures GPG passphrase prompts work
|
||||
CLAUDE_CODE_NO_FLICKER 1 — suppress terminal flicker in Claude Code
|
||||
CDPATH . ~/projects ~
|
||||
| Variable | Value | Notes |
|
||||
|---|---|---|
|
||||
| `GPG_TTY` | `$(tty)` | ensures GPG passphrase prompts work |
|
||||
| `CLAUDE_CODE_NO_FLICKER` | `1` | suppress terminal flicker in Claude Code |
|
||||
| `CDPATH` | `. ~/projects ~` | |
|
||||
|
||||
Opinionated defaults (CDPATH, PAGER/MANPAGER, Vi mode, command shadows,
|
||||
Opinionated defaults (`CDPATH`, `PAGER`/`MANPAGER`, Vi mode, command shadows,
|
||||
terminal integrations) can be switched off per category with universal
|
||||
variables — see Section 7, "Opinionated Components (Minimal Mode)".
|
||||
|
||||
## Pager Hierarchy
|
||||
|
||||
$PAGER is set to ov when available, falling back to less. The less wrapper
|
||||
function extends this into a full chain so anything that calls less directly
|
||||
`$PAGER` is set to `ov` when available, falling back to `less`. The `less` wrapper
|
||||
function extends this into a full chain so anything that calls `less` directly
|
||||
also benefits:
|
||||
|
||||
$PAGER → ov → less → more → cat
|
||||
`$PAGER` → `ov` → `less` → `more` → `cat`
|
||||
|
||||
When bat is installed, man pages are rendered with syntax highlighting:
|
||||
When `bat` is installed, man pages are rendered with syntax highlighting:
|
||||
|
||||
MANROFFOPT -c
|
||||
MANPAGER sh -c 'col -bx | bat -l man -p'
|
||||
| Variable | Value |
|
||||
|---|---|
|
||||
| `MANROFFOPT` | `-c` |
|
||||
| `MANPAGER` | `sh -c 'col -bx \| bat -l man -p'` |
|
||||
|
||||
## Integrations
|
||||
|
||||
### Zoxide
|
||||
|
||||
cd, z, and cdi/zi are all mapped to zoxide-backed navigation. Tab completions
|
||||
for cd and z blend standard directory entries (CWD and CDPATH) with frecency
|
||||
`cd`, `z`, and `cdi`/`zi` are all mapped to `zoxide`-backed navigation. Tab completions
|
||||
for `cd` and `z` blend standard directory entries (CWD and `CDPATH`) with frecency
|
||||
results so both familiar and frequently-visited paths appear in one list.
|
||||
|
||||
### DirEnv
|
||||
|
||||
Automatically loads .envrc files on directory change. Takes priority over
|
||||
the auto-venv logic — if a directory is managed by direnv, the auto-venv
|
||||
Automatically loads `.envrc` files on directory change. Takes priority over
|
||||
the auto-venv logic — if a directory is managed by `direnv`, the auto-venv
|
||||
activation is skipped entirely.
|
||||
|
||||
### Auto Python Venv
|
||||
|
||||
When entering a directory that contains a .venv/, the virtualenv is activated
|
||||
When entering a directory that contains a `.venv/`, the virtualenv is activated
|
||||
automatically and deactivated when you leave the project tree.
|
||||
|
||||
### WakaTime
|
||||
|
||||
Every shell command is reported to WakaTime for time-tracking. Set
|
||||
FISH_WAKATIME_DISABLED=1 to disable without removing the plugin.
|
||||
`FISH_WAKATIME_DISABLED=1` to disable without removing the plugin.
|
||||
|
||||
### Tailscale
|
||||
|
||||
Full tab completion for the tailscale CLI is provided via conf.d/tailscale.fish.
|
||||
Full tab completion for the `tailscale` CLI is provided via `conf.d/tailscale.fish`.
|
||||
|
||||
### Done Notifications
|
||||
|
||||
Desktop notifications fire when a command takes longer than 10 seconds and
|
||||
the terminal window is not focused. Configured via fish universal variables:
|
||||
|
||||
__done_min_cmd_duration 10000 ms
|
||||
__done_notification_urgency_level low
|
||||
| Variable | Value |
|
||||
|---|---|
|
||||
| `__done_min_cmd_duration` | `10000` ms |
|
||||
| `__done_notification_urgency_level` | `low` |
|
||||
|
||||
### Scrollback History
|
||||
|
||||
When running inside Kitty, closing a shell session via exit saves a timestamped
|
||||
scrollback snapshot to SCROLLBACK_HISTORY_DIR. Files are named:
|
||||
When running inside Kitty, closing a shell session via `exit` saves a timestamped
|
||||
scrollback snapshot to `SCROLLBACK_HISTORY_DIR`. Files are named:
|
||||
|
||||
scrollback_YYYY-MM-DD_HH-MM-SS.log
|
||||
`scrollback_YYYY-MM-DD_HH-MM-SS.log`
|
||||
|
||||
The paru and yay wrappers (auto-generated in ~/.local/bin/) run the command
|
||||
inside a PTY via script(1) so download progress bars are preserved on screen,
|
||||
The `paru` and `yay` wrappers (auto-generated in `~/.local/bin/`) run the command
|
||||
inside a PTY via `script(1)` so download progress bars are preserved on screen,
|
||||
then render the captured terminal animation down to a clean static log via
|
||||
scripts/clean_progress_log.py (a small terminal-screen emulator that replays
|
||||
`scripts/clean_progress_log.py` (a small terminal-screen emulator that replays
|
||||
cursor movements, collapses repainted progress frames to their final state,
|
||||
and preserves ANSI color). If python3 is unavailable the wrapper falls back to
|
||||
dropping only the script(1) header/footer. Output is saved to:
|
||||
and preserves ANSI color). If `python3` is unavailable the wrapper falls back to
|
||||
dropping only the `script(1)` header/footer. Output is saved to:
|
||||
|
||||
paru_YYYY-MM-DD_HH-MM-SS.log
|
||||
yay_YYYY-MM-DD_HH-MM-SS.log
|
||||
- `paru_YYYY-MM-DD_HH-MM-SS.log`
|
||||
- `yay_YYYY-MM-DD_HH-MM-SS.log`
|
||||
|
||||
Before pruning, _scrollback_prune_junk silently removes empty files, files
|
||||
with only a single meaningful line (e.g. bare [exited] captures), and Kitty
|
||||
tab-rename prompt captures. Use exit --no-log (or exit -n) to skip capture.
|
||||
Before pruning, `_scrollback_prune_junk` silently removes empty files, files
|
||||
with only a single meaningful line (e.g. bare `[exited]` captures), and Kitty
|
||||
tab-rename prompt captures. Use `exit --no-log` (or `exit -n`) to skip capture.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user