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

docs(site): replace starter README and title code fences throughout the manual #75

Merged
rootiest merged 2 commits from docs-option-tables into main 2026-07-26 09:29:26 +00:00
Conversation 0 Commits 2 Files Changed 5
+188 -49
5 changed files with 188 additions and 49 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/build-manual.py
+38 -5
View File
@@ -154,7 +154,7 @@ def _first_sentence(body: str) -> str:
SHELL_HEADS = frozenset( SHELL_HEADS = frozenset(
""" """
abbr alias apt bg bind brew builtin cargo cat cd chmod code command cp curl abbr alias apt bg bind brew builtin cargo cat cd chmod code command cp curl
dnf echo end env exec export fg fish fisher for funcsave function git help dnf docker echo end env exec export fg fish fisher for funcsave function git help
if jobs kitty ls man math mkdir mv nvim npm pacman paru pip pip3 pkg printf 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 python python3 rm set shutdown source string sudo switch systemctl test time
tmux touch trash type wget wezterm while yay zellij zypper tmux touch trash type wget wezterm while yay zellij zypper
@@ -162,6 +162,7 @@ SHELL_HEADS = frozenset(
) )
SYNOPSIS_PREFIX = "Synopsis:" SYNOPSIS_PREFIX = "Synopsis:"
EXAMPLE_PREFIX = "Example:"
INDENT = " " INDENT = " "
@@ -201,6 +202,16 @@ def _is_shell(para: list[str], entry_name: str | None) -> bool:
return True return True
# A lone indented line that's just a path ending in a known extension —
# e.g. pointing at where a file lives — reads better as a titled snippet
# than an unhighlighted grey slab.
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*$")
CELL_SPLIT = re.compile(r"\s{2,}") CELL_SPLIT = re.compile(r"\s{2,}")
@@ -262,9 +273,18 @@ def _render_para(para: list[str], entry_name: str | None, deeper: bool) -> str:
if not deeper: if not deeper:
if _is_prose(para): if _is_prose(para):
return "\n".join(line.strip() for line in para) return "\n".join(line.strip() for line in para)
if len(para) == 1 and PATH_LINE_RE.match(para[0].strip()):
path = para[0].strip()
name = path.rsplit("/", 1)[-1]
return f'```fish title="{name}"\n{path}\n```'
if _is_shell(para, entry_name): if _is_shell(para, entry_name):
body = "\n".join(para) body = para
return f"```fish\n{body}\n```" title = None
m = FILENAME_COMMENT_RE.match(para[0].strip())
if m:
title, body = m.group(1), para[1:]
info = f'fish title="{title}"' if title else "fish"
return f"```{info}\n" + "\n".join(body) + "\n```"
table = _as_table(para) table = _as_table(para)
if table is not None: if table is not None:
return table return table
@@ -288,7 +308,11 @@ def _prettify_block(block: list[str], entry_name: str | None) -> str:
# keep the whole thing in one fence rather than orphaning the rest. # keep the whole thing in one fence rather than orphaning the rest.
while lines and lines[0].startswith(" "): while lines and lines[0].startswith(" "):
synopsis.append(lines.pop(0).strip()) synopsis.append(lines.pop(0).strip())
out.append("```fish\n" + "\n".join(synopsis) + "\n```") # A "Usage" title (Starlight's filename-title convention, repurposed
# as a label) makes the synopsis read as a snippet of the function
# it documents rather than a bare command example.
info = 'fish title="Usage"' if entry_name else "fish"
out.append(f"```{info}\n" + "\n".join(synopsis) + "\n```")
para: list[str] = [] para: list[str] = []
for line in lines + [""]: for line in lines + [""]:
@@ -296,6 +320,15 @@ def _prettify_block(block: list[str], entry_name: str | None) -> str:
para.append(line) para.append(line)
continue continue
if para: if para:
if para[0].strip() == EXAMPLE_PREFIX:
example = para[1:]
if example and _is_shell(example, entry_name):
body = "\n".join(example)
out.append(f'```fish title="Examples"\n{body}\n```')
else:
deeper = any(line.startswith(" ") for line in example)
out.append(_render_para(example, entry_name, deeper))
else:
deeper = any(line.startswith(" ") for line in para) deeper = any(line.startswith(" ") for line in para)
out.append(_render_para(para, entry_name, deeper)) out.append(_render_para(para, entry_name, deeper))
para = [] para = []
@@ -362,7 +395,7 @@ def render_entry(fn: dict[str, list[str]], used_by: list[str], link=None) -> str
continue continue
out += ["", head] + [" " + line for line in body] out += ["", head] + [" " + line for line in body]
if fn.get("EXAMPLE"): if fn.get("EXAMPLE"):
out += [""] + fn["EXAMPLE"] out += ["", EXAMPLE_PREFIX] + fn["EXAMPLE"]
block = "\n".join((INDENT + line).rstrip() for line in out) block = "\n".join((INDENT + line).rstrip() for line in out)
docs/fish-config.md
+97
View File
@@ -536,6 +536,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Files or directories to display args... Files or directories to display
Example:
cat README.md cat README.md
cat ~/projects/myapp cat ~/projects/myapp
@@ -550,6 +551,7 @@ Add -i (interactive confirmation) to destructive commands:
source Source file or directory source Source file or directory
dest Destination path dest Destination path
Example:
copy ./mydir/ ~/backup copy ./mydir/ ~/backup
copy ./mydir/ ~/backup # copies mydir INTO backup, not backup/mydir/ copy ./mydir/ ~/backup # copies mydir INTO backup, not backup/mydir/
@@ -567,6 +569,7 @@ Add -i (interactive confirmation) to destructive commands:
--dua Force dua (fast interactive space analyzer) --dua Force dua (fast interactive space analyzer)
args... Files/directories or flags forwarded to the selected tool args... Files/directories or flags forwarded to the selected tool
Example:
du ~/Downloads du ~/Downloads
du --disk du --disk
@@ -580,6 +583,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
dir Directory to summarize (defaults to current directory) dir Directory to summarize (defaults to current directory)
Example:
dusize ~/Downloads dusize ~/Downloads
dusize ~/Videos dusize ~/Videos
@@ -593,6 +597,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
lD ~/projects lD ~/projects
### ls ### ls
@@ -605,6 +610,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
ls ~/projects ls ~/projects
ls ls
ls -a ~/projects ls -a ~/projects
@@ -619,6 +625,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
lsr ~/projects lsr ~/projects
### lss ### lss
@@ -631,6 +638,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
lss ~/downloads lss ~/downloads
### lstree ### lstree
@@ -643,6 +651,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
lstree ~/projects/myapp lstree ~/projects/myapp
### lt ### lt
@@ -655,6 +664,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
lt ~/projects lt ~/projects
### ltr ### ltr
@@ -668,6 +678,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
ltr ~/projects ltr ~/projects
### lx ### lx
@@ -680,6 +691,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the listing command args... Arguments forwarded to the listing command
Example:
lx ~/projects lx ~/projects
### mkcd ### mkcd
@@ -700,6 +712,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Directory created (or already existed) and entered successfully 0 Directory created (or already existed) and entered successfully
1 Directory creation or cd failed 1 Directory creation or cd failed
Example:
mkcd ~/projects/myapp mkcd ~/projects/myapp
mkcd ~/projects/newapp/src mkcd ~/projects/newapp/src
@@ -715,6 +728,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Directories to create, or flags passed through to command mkdir args... Directories to create, or flags passed through to command mkdir
Example:
mkdir ~/projects/myapp/src mkdir ~/projects/myapp/src
### poke ### poke
@@ -731,6 +745,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Files created 0 Files created
1 No file argument provided 1 No file argument provided
Example:
poke ~/projects/new/src/main.fish poke ~/projects/new/src/main.fish
### rg ### rg
@@ -744,6 +759,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to ripgrep args... Arguments forwarded to ripgrep
Example:
rg "TODO" src/ rg "TODO" src/
rg "fish_greeting" ~/.config/fish/ rg "fish_greeting" ~/.config/fish/
rg -l "TODO" ~/projects/myapp rg -l "TODO" ~/projects/myapp
@@ -776,6 +792,7 @@ Add -i (interactive confirmation) to destructive commands:
Notes: Notes:
Falls back to /usr/bin/rm when trash is unavailable. Falls back to /usr/bin/rm when trash is unavailable.
Example:
rm file.txt rm file.txt
rm -e rm -e
rm -S sensitive_key.pem rm -S sensitive_key.pem
@@ -799,6 +816,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Sweep completed (or dry run shown) 0 Sweep completed (or dry run shown)
1 fd not found, or unknown argument provided 1 fd not found, or unknown argument provided
Example:
scrub scrub
scrub -a scrub -a
scrub -d scrub -d
@@ -815,6 +833,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
query Optional search term to pre-filter the directory list query Optional search term to pre-filter the directory list
Example:
cdi myproject cdi myproject
### clone ### clone
@@ -831,6 +850,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Repository cloned 0 Repository cloned
1 Not running inside Kitty terminal 1 Not running inside Kitty terminal
Example:
clone https://github.com/user/repo.git clone https://github.com/user/repo.git
### clonet ### clonet
@@ -847,6 +867,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Repository cloned 0 Repository cloned
1 Not running inside Kitty terminal 1 Not running inside Kitty terminal
Example:
clonet https://github.com/user/repo.git clonet https://github.com/user/repo.git
## 5.3 Editors and Viewers ## 5.3 Editors and Viewers
@@ -882,6 +903,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Editor launched successfully 0 Editor launched successfully
1 Conflicting flags, no editor found, or clipboard read failed 1 Conflicting flags, no editor found, or clipboard read failed
Example:
edit notes.txt edit notes.txt
edit --visual ~/.config/fish/config.fish edit --visual ~/.config/fish/config.fish
edit --terminal --new todo.md edit --terminal --new todo.md
@@ -904,6 +926,7 @@ Add -i (interactive confirmation) to destructive commands:
The edited command's exit status, or a message when history lookup The edited command's exit status, or a message when history lookup
found nothing. found nothing.
Example:
fc fc
fc git fc git
@@ -917,6 +940,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Files or options forwarded to the pager args... Files or options forwarded to the pager
Example:
less /var/log/syslog less /var/log/syslog
### rawfish ### rawfish
@@ -929,6 +953,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to fish args... Arguments forwarded to fish
Example:
rawfish rawfish
### view ### view
@@ -941,6 +966,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Files or options forwarded to nvim -R or less args... Files or options forwarded to nvim -R or less
Example:
view /etc/fstab view /etc/fstab
## 5.4 Git and Version Control ## 5.4 Git and Version Control
@@ -974,6 +1000,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Subcommand succeeded 0 Subcommand succeeded
1 Bad usage, target is not a git repo, or target not registered 1 Bad usage, target is not a git repo, or target not registered
Example:
cd ~/src/qmk_firmware; and auto-pull add cd ~/src/qmk_firmware; and auto-pull add
auto-pull add ~/work/api auto-pull add ~/work/api
auto-pull list auto-pull list
@@ -993,6 +1020,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Branch checked out or created 0 Branch checked out or created
1 Not inside a git work tree 1 Not inside a git work tree
Example:
branch feature/new-ui branch feature/new-ui
### gi ### gi
@@ -1017,6 +1045,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Patterns appended or printed 0 Patterns appended or printed
1 Not in a git repository or API fetch failed 1 Not in a git repository or API fetch failed
Example:
gi python,venv gi python,venv
gi -b -p gi -b -p
gi -s node > .gitignore gi -s node > .gitignore
@@ -1037,6 +1066,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Cleanup complete 0 Cleanup complete
1 Argument parsing failed 1 Argument parsing failed
Example:
git-clean --force git-clean --force
git-clean git-clean
@@ -1050,6 +1080,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to the gitui command args... Arguments forwarded to the gitui command
Example:
gitui gitui
### gitup ### gitup
@@ -1066,6 +1097,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Fetch and status succeeded 0 Fetch and status succeeded
1 Not inside a git work tree 1 Not inside a git work tree
Example:
gitup gitup
gitup --all gitup --all
@@ -1076,6 +1108,7 @@ Add -i (interactive confirmation) to destructive commands:
Searches fish history interactively using fzf, inserts the selected command Searches fish history interactively using fzf, inserts the selected command
into the command line, and copies it to the clipboard via wl-copy. into the command line, and copies it to the clipboard via wl-copy.
Example:
hist hist
## 5.5 Package Management ## 5.5 Package Management
@@ -1087,6 +1120,7 @@ Add -i (interactive confirmation) to destructive commands:
Identifies and removes Arch Linux orphan packages using pacman. Logs Identifies and removes Arch Linux orphan packages using pacman. Logs
package names and versions to ~/.removed_orphans before removal. package names and versions to ~/.removed_orphans before removal.
Example:
cleanup cleanup
### parur ### parur
@@ -1101,6 +1135,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Packages removed or none selected 0 Packages removed or none selected
1 No AUR helper (paru or yay) found 1 No AUR helper (paru or yay) found
Example:
parur parur
### pkg ### pkg
@@ -1130,6 +1165,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Operation completed 0 Operation completed
1 No supported package manager found, unknown flag, or package operation failed 1 No supported package manager found, unknown flag, or package operation failed
Example:
pkg firefox pkg firefox
pkg -i ripgrep fd-find pkg -i ripgrep fd-find
pkg -u cowsay pkg -u cowsay
@@ -1148,6 +1184,7 @@ Add -i (interactive confirmation) to destructive commands:
0 AUR helper ran successfully 0 AUR helper ran successfully
1 No AUR helper (paru or yay) found 1 No AUR helper (paru or yay) found
Example:
search neovim search neovim
### upgrade ### upgrade
@@ -1161,6 +1198,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Upgrade completed successfully 0 Upgrade completed successfully
1 No AUR helper (paru or yay) found 1 No AUR helper (paru or yay) found
Example:
upgrade upgrade
## 5.6 Dependency Management ## 5.6 Dependency Management
@@ -1172,6 +1210,7 @@ Add -i (interactive confirmation) to destructive commands:
Backwards-compatibility wrapper that delegates to fish-deps status to Backwards-compatibility wrapper that delegates to fish-deps status to
report which fish shell dependencies are installed or missing. report which fish shell dependencies are installed or missing.
Example:
check_fish_deps check_fish_deps
### fish-deps ### fish-deps
@@ -1209,6 +1248,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Subcommand completed 0 Subcommand completed
1 Unknown subcommand 1 Unknown subcommand
Example:
fish-deps sync fish-deps sync
fish-deps fish-deps
fish-deps install fish-deps install
@@ -1221,6 +1261,7 @@ Add -i (interactive confirmation) to destructive commands:
Installs or upgrades fzf from git HEAD into ~/.fzf. Pulls the latest Installs or upgrades fzf from git HEAD into ~/.fzf. Pulls the latest
changes if ~/.fzf already exists, or clones the repository if not. changes if ~/.fzf already exists, or clones the repository if not.
Example:
fzf-update fzf-update
## 5.7 System and Monitoring ## 5.7 System and Monitoring
@@ -1234,6 +1275,7 @@ Add -i (interactive confirmation) to destructive commands:
files tracked by sbctl. Combines the edit and sign steps into a single files tracked by sbctl. Combines the edit and sign steps into a single
command. command.
Example:
limine-edit limine-edit
### lock ### lock
@@ -1242,6 +1284,7 @@ Add -i (interactive confirmation) to destructive commands:
Locks the current desktop session using loginctl lock-session. Locks the current desktop session using loginctl lock-session.
Example:
lock lock
### ports ### ports
@@ -1251,6 +1294,7 @@ Add -i (interactive confirmation) to destructive commands:
Lists all active TCP listeners on the system using lsof, showing Lists all active TCP listeners on the system using lsof, showing
port numbers and addresses without hostname resolution. port numbers and addresses without hostname resolution.
Example:
ports ports
### sbver ### sbver
@@ -1269,6 +1313,7 @@ Add -i (interactive confirmation) to destructive commands:
0 All binaries verified (or summary shown) 0 All binaries verified (or summary shown)
1 sbctl is not installed 1 sbctl is not installed
Example:
sbver sbver
sbver --brief sbver --brief
@@ -1279,6 +1324,7 @@ Add -i (interactive confirmation) to destructive commands:
Turns off the display after a 1-second delay by invoking the KDE Turns off the display after a 1-second delay by invoking the KDE
PowerDevil "Turn Off Screen" global shortcut via busctl. PowerDevil "Turn Off Screen" global shortcut via busctl.
Example:
screensleep screensleep
### sudo-toggle ### sudo-toggle
@@ -1293,6 +1339,7 @@ Add -i (interactive confirmation) to destructive commands:
Returns: Returns:
0 Rule toggled 0 Rule toggled
Example:
sudo-toggle sudo-toggle
### swapstat ### swapstat
@@ -1303,6 +1350,7 @@ Add -i (interactive confirmation) to destructive commands:
zRAM compression ratio, zRAM device details (via zramctl), and zRAM compression ratio, zRAM device details (via zramctl), and
active swap priority (via swapon). active swap priority (via swapon).
Example:
swapstat swapstat
### top ### top
@@ -1315,6 +1363,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to btop or system top args... Arguments forwarded to btop or system top
Example:
top top
## 5.8 Terminal Management ## 5.8 Terminal Management
@@ -1335,6 +1384,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Command launched successfully 0 Command launched successfully
1 No command provided 1 No command provided
Example:
bkg firefox bkg firefox
### detach ### detach
@@ -1355,6 +1405,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Command launched or help/version shown 0 Command launched or help/version shown
1 No command provided or unknown option 1 No command provided or unknown option
Example:
detach rsync -a ./data remote:/backup/ detach rsync -a ./data remote:/backup/
### split ### split
@@ -1375,6 +1426,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Pane opened successfully 0 Pane opened successfully
1 Not running inside Kitty or WezTerm 1 Not running inside Kitty or WezTerm
Example:
split split
split -v nvim README.md split -v nvim README.md
@@ -1392,6 +1444,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Window opened successfully 0 Window opened successfully
1 Not running inside Kitty or WezTerm 1 Not running inside Kitty or WezTerm
Example:
spwin spwin
### ssh ### ssh
@@ -1406,6 +1459,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to kitten ssh or system ssh args... Arguments forwarded to kitten ssh or system ssh
Example:
ssh user@host ssh user@host
### tab ### tab
@@ -1423,6 +1477,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Tab opened successfully 0 Tab opened successfully
1 No supported terminal found 1 No supported terminal found
Example:
tab tab
## 5.9 Clipboard ## 5.9 Clipboard
@@ -1442,6 +1497,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Clipboard contents printed successfully 0 Clipboard contents printed successfully
1 No supported clipboard tool found 1 No supported clipboard tool found
Example:
p | grep foo p | grep foo
p > file.txt p > file.txt
@@ -1459,6 +1515,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Clipboard contents printed successfully 0 Clipboard contents printed successfully
1 No supported clipboard tool found 1 No supported clipboard tool found
Example:
paste > file.txt paste > file.txt
### y ### y
@@ -1475,6 +1532,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Text copied to clipboard 0 Text copied to clipboard
1 No clipboard provider found 1 No clipboard provider found
Example:
y "hello world" y "hello world"
ls | y ls | y
cat file.txt | y cat file.txt | y
@@ -1488,6 +1546,7 @@ Add -i (interactive confirmation) to destructive commands:
Fetches and prints both the public IPv4 and IPv6 addresses using Fetches and prints both the public IPv4 and IPv6 addresses using
icanhazip.com. Shows "Not detected" for any address that times out. icanhazip.com. Shows "Not detected" for any address that times out.
Example:
gip gip
### gip4 ### gip4
@@ -1496,6 +1555,7 @@ Add -i (interactive confirmation) to destructive commands:
Fetches and prints the machine's public IPv4 address using icanhazip.com. Fetches and prints the machine's public IPv4 address using icanhazip.com.
Example:
gip4 gip4
### gip6 ### gip6
@@ -1509,6 +1569,7 @@ Add -i (interactive confirmation) to destructive commands:
0 IPv6 address printed 0 IPv6 address printed
1 IPv6 unavailable or not supported on this network 1 IPv6 unavailable or not supported on this network
Example:
gip6 gip6
### ping ### ping
@@ -1523,6 +1584,7 @@ Add -i (interactive confirmation) to destructive commands:
--legend Show the prettyping legend (overrides default --nolegend) --legend Show the prettyping legend (overrides default --nolegend)
args... Arguments forwarded to prettyping or system ping args... Arguments forwarded to prettyping or system ping
Example:
ping google.com ping google.com
ping --legend google.com ping --legend google.com
@@ -1537,6 +1599,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
text... Text to encode; reads from stdin if omitted text... Text to encode; reads from stdin if omitted
Example:
qr "https://example.com" qr "https://example.com"
echo "hello" | qr echo "hello" | qr
@@ -1567,6 +1630,7 @@ Add -i (interactive confirmation) to destructive commands:
0 File viewed or no file selected 0 File viewed or no file selected
1 No log files found 1 No log files found
Example:
logs -c paru logs -c paru
logs logs
logs -c scrollback logs -c scrollback
@@ -1592,6 +1656,7 @@ Add -i (interactive confirmation) to destructive commands:
The exit builtin is wired to smart_exit for interactive sessions. Typing The exit builtin is wired to smart_exit for interactive sessions. Typing
`exit` or Ctrl+D behaves identically to calling smart_exit directly. `exit` or Ctrl+D behaves identically to calling smart_exit directly.
Example:
smart_exit smart_exit
smart_exit --no-log smart_exit --no-log
@@ -1663,6 +1728,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Setup completed successfully 0 Setup completed successfully
1 Fatal error (git init failed, move failed, etc.) 1 Fatal error (git init failed, move failed, etc.)
Example:
agents-init agents-init
agents-init --agents agents-init --agents
agents-init --plugins agents-init --plugins
@@ -1691,6 +1757,7 @@ Add -i (interactive confirmation) to destructive commands:
Returns: Returns:
Exit status of the underlying agy binary Exit status of the underlying agy binary
Example:
agy agy
agy chat agy chat
agy resume agy resume
@@ -1707,6 +1774,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments passed through to the antigravity-ide command args... Arguments passed through to the antigravity-ide command
Example:
antigravity-ide antigravity-ide
### claude ### claude
@@ -1730,6 +1798,7 @@ Add -i (interactive confirmation) to destructive commands:
Returns: Returns:
Exit status of the underlying claude binary Exit status of the underlying claude binary
Example:
claude claude
claude --resume claude --resume
claude "Explain the recent changes" claude "Explain the recent changes"
@@ -1744,6 +1813,7 @@ Add -i (interactive confirmation) to destructive commands:
README.md, ensuring all features and examples are accurate and pruning README.md, ensuring all features and examples are accurate and pruning
obsolete content. obsolete content.
Example:
claude-docs claude-docs
### claude-pr ### claude-pr
@@ -1754,6 +1824,7 @@ Add -i (interactive confirmation) to destructive commands:
branch, write a Conventional Commit, run verification, push, and open a branch, write a Conventional Commit, run verification, push, and open a
pull request with a manual verification checklist. pull request with a manual verification checklist.
Example:
claude-pr claude-pr
### dops ### dops
@@ -1768,6 +1839,7 @@ Add -i (interactive confirmation) to destructive commands:
subcommand Docker subcommand (ps is redirected to dops) subcommand Docker subcommand (ps is redirected to dops)
args... Arguments forwarded to docker or dops args... Arguments forwarded to docker or dops
Example:
docker ps docker ps
### qc ### qc
@@ -1791,6 +1863,7 @@ Add -i (interactive confirmation) to destructive commands:
Returns: Returns:
aichat's exit status. aichat's exit status.
Example:
qc "how do I list open ports on linux?" qc "how do I list open ports on linux?"
qc -m ollama:llama3 "explain this error" qc -m ollama:llama3 "explain this error"
qc --role coder "refactor this function" qc --role coder "refactor this function"
@@ -1813,6 +1886,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Mode applied successfully 0 Mode applied successfully
1 No on/off mode specified 1 No on/off mode specified
Example:
superpowers on superpowers on
superpowers off -g superpowers off -g
@@ -1837,6 +1911,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Conversion complete 0 Conversion complete
1 File not found, missing dependency, or encode step failed 1 File not found, missing dependency, or encode step failed
Example:
dng2avif photo.dng dng2avif photo.dng
dng2avif -q 85 -s 5 -i shot.dng -o out.avif dng2avif -q 85 -s 5 -i shot.dng -o out.avif
@@ -1855,6 +1930,7 @@ Add -i (interactive confirmation) to destructive commands:
-v, --version Print version -v, --version Print version
-h, --help Show usage help -h, --help Show usage help
Example:
spark 1 1 2 5 14 42 spark 1 1 2 5 14 42
seq 64 | sort --random-sort | spark seq 64 | sort --random-sort | spark
echo "3 7 2 9 1" | spark echo "3 7 2 9 1" | spark
@@ -1866,6 +1942,7 @@ Add -i (interactive confirmation) to destructive commands:
Launches Steam with systemd-inhibit to prevent the system from idling Launches Steam with systemd-inhibit to prevent the system from idling
or sleeping during active downloads. or sleeping during active downloads.
Example:
steam-dl steam-dl
### yt-dlp ### yt-dlp
@@ -1888,6 +1965,7 @@ Add -i (interactive confirmation) to destructive commands:
args... Arguments forwarded to yt-dlp (defaults prepended) args... Arguments forwarded to yt-dlp (defaults prepended)
--no-embed-thumbnail Skip thumbnail embedding for this run --no-embed-thumbnail Skip thumbnail embedding for this run
Example:
yt-dlp dQw4w9WgXcQ yt-dlp dQw4w9WgXcQ
yt-dlp --no-embed-thumbnail dQw4w9WgXcQ # drops our thumbnail default yt-dlp --no-embed-thumbnail dQw4w9WgXcQ # drops our thumbnail default
@@ -1903,6 +1981,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments passed through to the bash command args... Arguments passed through to the bash command
Example:
bash bash
### bd-pull ### bd-pull
@@ -1920,6 +1999,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Issues linked and synced (or no unlinked issues found) 0 Issues linked and synced (or no unlinked issues found)
1 Missing required argument or environment variables 1 Missing required argument or environment variables
Example:
bd-pull myuser/myproject bd-pull myuser/myproject
bd-pull rootiest/fish-config bd-pull rootiest/fish-config
@@ -1933,6 +2013,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Additional arguments forwarded to fastfetch or neofetch args... Additional arguments forwarded to fastfetch or neofetch
Example:
cffetch cffetch
### cheat ### cheat
@@ -1946,6 +2027,7 @@ Add -i (interactive confirmation) to destructive commands:
topic The command or topic to look up topic The command or topic to look up
args... Additional arguments forwarded to cheat, tldr, or man args... Additional arguments forwarded to cheat, tldr, or man
Example:
cheat tar cheat tar
cheat git cheat git
@@ -1986,6 +2068,7 @@ Add -i (interactive confirmation) to destructive commands:
registered as a handler in the help wrapper so that syntax works registered as a handler in the help wrapper so that syntax works
transparently. Direct `config-help` calls are also valid. transparently. Direct `config-help` calls are also valid.
Example:
config-help config-help
config-help keybindings config-help keybindings
config-help pkg config-help pkg
@@ -2052,6 +2135,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Exited normally (q or Escape pressed) 0 Exited normally (q or Escape pressed)
1 Unknown flag passed 1 Unknown flag passed
Example:
config-settings config-settings
**Used by:** `config-toggle` **Used by:** `config-toggle`
@@ -2069,6 +2153,7 @@ Add -i (interactive confirmation) to destructive commands:
Returns: Returns:
Same as config-settings Same as config-settings
Example:
config-toggle # opens config-settings with a deprecation notice config-toggle # opens config-settings with a deprecation notice
**Dependencies:** `config-settings` **Dependencies:** `config-settings`
@@ -2091,6 +2176,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Config updated (or already up to date) 0 Config updated (or already up to date)
1 Update failed (network error, merge conflict, or not a git repo) 1 Update failed (network error, merge conflict, or not a git repo)
Example:
config-update config-update
config-update --dry-run config-update --dry-run
config-update --force config-update --force
@@ -2110,6 +2196,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Services updated and running 0 Services updated and running
1 Directory not found or no docker-compose.yml present 1 Directory not found or no docker-compose.yml present
Example:
dockup ~/myapp dockup ~/myapp
### ffetch ### ffetch
@@ -2122,6 +2209,7 @@ Add -i (interactive confirmation) to destructive commands:
Arguments: Arguments:
args... Arguments forwarded to fastfetch or neofetch args... Arguments forwarded to fastfetch or neofetch
Example:
ffetch ffetch
### joplin ### joplin
@@ -2138,6 +2226,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Joplin ran successfully 0 Joplin ran successfully
1 joplin binary not found in PATH 1 joplin binary not found in PATH
Example:
joplin ls joplin ls
### kitty-logging ### kitty-logging
@@ -2167,6 +2256,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Success 0 Success
1 Unknown subcommand/flag, kitty missing, or a write failure 1 Unknown subcommand/flag, kitty missing, or a write failure
Example:
kitty-logging install kitty-logging install
kitty-logging status kitty-logging status
@@ -2177,6 +2267,7 @@ Add -i (interactive confirmation) to destructive commands:
Launches lazydocker targeting the currently active Docker context by Launches lazydocker targeting the currently active Docker context by
resolving the host endpoint from docker context inspect. resolving the host endpoint from docker context inspect.
Example:
ld ld
### open-url ### open-url
@@ -2212,6 +2303,7 @@ Add -i (interactive confirmation) to destructive commands:
Notes: Notes:
Typo abbreviation: url-open (expands to open-url on space/enter). Typo abbreviation: url-open (expands to open-url on space/enter).
Example:
open-url https://git.rootiest.dev/rootiest/fish-config open-url https://git.rootiest.dev/rootiest/fish-config
open-url -v https://fish-config-docs.pages.dev/ open-url -v https://fish-config-docs.pages.dev/
@@ -2232,6 +2324,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Commands ran successfully and changes were replayed 0 Commands ran successfully and changes were replayed
1 Bash command exited with a non-zero status 1 Bash command exited with a non-zero status
Example:
replay "source ~/.bashrc" replay "source ~/.bashrc"
replay "export FOO=bar" replay "export FOO=bar"
@@ -2272,6 +2365,7 @@ Add -i (interactive confirmation) to destructive commands:
Notes: Notes:
Typo abbreviation: open-repo (expands to repo-open on space/enter). Typo abbreviation: open-repo (expands to repo-open on space/enter).
Example:
repo-open # open current branch (+ subdir) in browser repo-open # open current branch (+ subdir) in browser
repo-open --print # just print the URL repo-open --print # just print the URL
repo-open --root # repo home page for the current branch repo-open --root # repo home page for the current branch
@@ -2285,6 +2379,7 @@ Add -i (interactive confirmation) to destructive commands:
Kills all detached (unattached) tmux sessions, leaving any currently Kills all detached (unattached) tmux sessions, leaving any currently
attached sessions running. attached sessions running.
Example:
tmux-clean tmux-clean
### wake-lock ### wake-lock
@@ -2302,6 +2397,7 @@ Add -i (interactive confirmation) to destructive commands:
0 Command ran and completed 0 Command ran and completed
1 No command provided 1 No command provided
Example:
wake-lock rsync -avz src/ dest/ wake-lock rsync -avz src/ dest/
# 6. DEPENDENCY CATALOG # 6. DEPENDENCY CATALOG
@@ -2962,6 +3058,7 @@ fish_variables (auto-managed by fish) is excluded from this repo via
Store anything you would not commit to a public repo: API keys, auth tokens, Store anything you would not commit to a public repo: API keys, auth tokens,
passwords, and personal identifiers. passwords, and personal identifiers.
# secrets.fish
set -gx MY_NAME "Your Name" set -gx MY_NAME "Your Name"
set -gx MY_EMAIL "you@example.com" set -gx MY_EMAIL "you@example.com"
set -gx GPG_RECIPIENT "you@example.com" set -gx GPG_RECIPIENT "you@example.com"
docs/manual/10-personalization.md
+1
View File
@@ -33,6 +33,7 @@ fish_variables (auto-managed by fish) is excluded from this repo via
Store anything you would not commit to a public repo: API keys, auth tokens, Store anything you would not commit to a public repo: API keys, auth tokens,
passwords, and personal identifiers. passwords, and personal identifiers.
# secrets.fish
set -gx MY_NAME "Your Name" set -gx MY_NAME "Your Name"
set -gx MY_EMAIL "you@example.com" set -gx MY_EMAIL "you@example.com"
set -gx GPG_RECIPIENT "you@example.com" set -gx GPG_RECIPIENT "you@example.com"
docs/site/README.md
+25 -40
View File
@@ -1,49 +1,34 @@
# Starlight Starter Kit: Basics # fish-config docs site
[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build) [Starlight](https://starlight.astro.build) site for the
[fish-config](https://git.rootiest.dev/rootiest/fish-config) manual.
``` ## Generated, not authored
npm create astro@latest -- --template starlight
Everything under `src/content/docs/` is generated — **do not edit it
directly**, changes will be overwritten. The sources are:
- `docs/manual/**` — prose for every section except the functions reference
- `functions/*.fish` comment headers — the functions reference (Section 5)
Regenerate from the repo root:
```fish title="regenerate the site content"
python3 docs/build-manual.py --site
``` ```
> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! `docs/verify-manual.py` validates both sources before you build; run it
first if you've touched a header or a manual page.
## 🚀 Project Structure ## Development
Inside of your Astro + Starlight project, you'll see the following folders and files: ```fish title="local dev server"
cd docs/site
``` npm install
. npm run dev
├── public/
├── src/
│ ├── assets/
│ ├── content/
│ │ └── docs/
│ └── content.config.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json
``` ```
Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. ## Deploy
Images can be added to `src/assets/` and embedded in Markdown with a relative link. Built and deployed to Cloudflare Pages by the Gitea Actions workflow on
every push to `main` — there's no manual deploy step.
Static assets, like favicons, can be placed in the `public/` directory.
## 🧞 Commands
All commands are run from the root of the project, from a terminal:
| Command | Action |
| :------------------------ | :----------------------------------------------- |
| `npm install` | Installs dependencies |
| `npm run dev` | Starts local dev server at `localhost:4321` |
| `npm run build` | Build your production site to `./dist/` |
| `npm run preview` | Preview your build locally, before deploying |
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
| `npm run astro -- --help` | Get help using the Astro CLI |
## 👀 Want to learn more?
Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
docs/verify-manual.py
+25 -2
View File
@@ -332,14 +332,19 @@ def test_prettify_splits_an_entry_block():
"", "",
" Falls back to /usr/bin/rm when trash is unavailable.", " Falls back to /usr/bin/rm when trash is unavailable.",
"", "",
" Example:",
" rm file.txt # moves to trash", " rm file.txt # moves to trash",
" rm -e # empty trash", " rm -e # empty trash",
] ]
) )
out = build_manual.prettify(body, "rm") out = build_manual.prettify(body, "rm")
assert "```fish\nrm [-e | args...]\n```" in out, "synopsis was not fenced as fish" assert '```fish title="Usage"\nrm [-e | args...]\n```' in out, (
assert "```fish\nrm file.txt" in out, "examples were not fenced as fish" "synopsis was not fenced as fish with a Usage title"
)
assert '```fish title="Examples"\nrm file.txt' in out, (
"examples were not fenced as fish with an Examples title"
)
assert out.count("```") == 4, f"expected exactly two fences, got:\n{out}" assert out.count("```") == 4, f"expected exactly two fences, got:\n{out}"
assert "\nSafe rm wrapper routing to trash:" in out, "description stayed indented" assert "\nSafe rm wrapper routing to trash:" in out, "description stayed indented"
assert "| `(no args)` | List current trash contents |" in out, ( assert "| `(no args)` | List current trash contents |" in out, (
@@ -429,6 +434,24 @@ def test_prettify_leaves_reference_tables_alone():
assert "```fish" in build_manual.prettify(shell), "a shell block was not fenced" assert "```fish" in build_manual.prettify(shell), "a shell block was not fenced"
def test_prettify_titles_paths_and_commented_examples():
"""A bare file path or a leading '# in x.fish' comment become a title."""
import build_manual
path = " $__fish_user_dots_path/local.fish"
assert '```fish title="local.fish"\n$__fish_user_dots_path/local.fish\n```' in (
build_manual.prettify(path)
), "a bare file path was not titled"
commented = "\n".join(
[" # in local.fish", " set -gx SCROLLBACK_HISTORY_MAX_FILES 200"]
)
out = build_manual.prettify(commented)
assert '```fish title="local.fish"\nset -gx SCROLLBACK_HISTORY_MAX_FILES 200\n```' in out, (
f"a filename comment was not promoted to the fence title:\n{out}"
)
def test_prettify_is_site_only(): def test_prettify_is_site_only():
"""The SSOT keeps the indented form the man-page pipeline depends on.""" """The SSOT keeps the indented form the man-page pipeline depends on."""
import build_manual import build_manual