rootiest/fish-config

Fork 0

Files

T

rootiest b754709f02

CI / test (push) Successful in 1m4s

Details

CI / build-docs (push) Successful in 3m57s

Details

docs(site): add inline code spans to generated Starlight pages

Function doc-headers are authored as plain text -- `config-help`,
`funcsave` and anyone opening the `.fish` file read them as-is -- so they
carry no backticks. The site inherited that and rendered `-a/--all` and
`__fish_config_op_aliases` as ordinary prose.

docs/codespans.py adds the spans at render time, as the last step of
prettify(), so only the site sees them; build_concat() (man page,
config-help) is byte-for-byte unchanged.

Recognised shapes: flags and flag pairs, `$vars`, SCREAMING_SNAKE env
vars, snake_case identifiers, paths and filenames, key chords, command
shadow chains (`ls->eza`), runs of tool names, whole command lines in a
table column of command lines, and known command names -- drawn from the
`_fdc_*` catalog in functions/_fish_deps_catalog.fish, the functions/
listing, and a standard-command list, minus the names that also read as
English.

Fenced blocks, existing code spans, headings, link targets, URLs,
component markup and <FileTree> bodies are passed through untouched, and
every rule bails out rather than guess.

2026-08-31 20:04:19 -04:00

3.0 KiB

Raw Blame History

fish-config docs site

Starlight site for the fish-config manual.

Generated, not authored

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:

python3 docs/build-manual.py --site

docs/verify-manual.py validates both sources before you build; run it first if you've touched a header or a manual page.

Inline code spans

Function headers are read as plain text (by config-help, by funcsave, by anyone opening the .fish file), so they're authored without backticks — -a/--all, not `-a`/`--all`. docs/codespans.py puts the backticks on at render time, as the last step of prettify(), so only the site sees them.

It recognises flags, $vars, SCREAMING_SNAKE env vars, snake_case identifiers (__fish_config_op_aliases, fish_greeting), paths and filenames, key chords (Ctrl-R), shadow chains (ls->eza), runs of tool names (btop, dust, duf, …), whole command lines in a table column of command lines, and command names it knows — the _fdc_* catalog in functions/_fish_deps_catalog.fish, the functions/ directory listing, and a standard-command list in the module.

Names that also read as English (find, top, screen) are listed in AMBIGUOUS_COMMANDS and are never wrapped on sight; they still count where position already proves they're a command. Add to that list rather than removing a rule if a wrap ever reads wrong.

Fenced blocks, existing code spans, headings, link targets, URLs, component markup, and <FileTree> bodies are never touched. Leaving a token alone is always the safe outcome, so every rule bails out when it isn't sure.

llms.txt

The starlight-llms-txt plugin emits llms.txt, llms-full.txt, and llms-small.txt alongside the built pages — no configuration needed, it just walks the generated content.

Icons

starlight-plugin-icons

UnoCSS (uno.config.ts) render icons from any Iconify set as i-<collection>:<name> classes. The Gitea link in the header uses it (see src/components/starlight/SocialIcons.astro) to show the real Gitea logo instead of Starlight's generic code-branch icon. Sidebar (sidebar: true) and codeblock (codeblock: true) icon support are wired up in astro.config.mjs but unused so far — see the plugin docs for the icon: sidebar syntax if you want to add them.

Development

cd docs/site
npm install
npm run dev

Deploy

Built and deployed to Cloudflare Pages by the Gitea Actions workflow on every push to main — there's no manual deploy step.

3.0 KiB Raw Blame History