The sidebar previously started with 'Configuration Variables' which felt abrupt. Add a 'Home' link at the top pointing to the landing page (the one with install/functions-ref buttons). Seeded the sidebar list in build_site() so it persists across --site rebuilds.
The troubleshooting section renumbered Viewing This Manual from 11 to
12, but verify-manual.py still hardcoded the old filename
(11-viewing-this-manual.mdx) in the site promotion test. Update both
references to 12-viewing-this-manual.mdx.
Also regenerate docs/fish-config.md so the concat roundtrip test passes
with the new section ordering.
Add a new Troubleshooting section to the manual with 9 concise how-to
subsections covering uninstall/revert, Fish version requirements,
disabling logging, changing the greeting, secrets/local config, the
return sentinel gotcha, missing dependencies, Vi mode keybindings,
and minimal mode.
Renumber Viewing This Manual from Section 11 to Section 12 to place
troubleshooting before it. Update TOC and help index accordingly.
All verify-manual.py checks pass.
- test_customization_notes_render_as_aside now asserts the four NOTE
bullets live inside the <Aside> tags, not merely anywhere on the
page — a re-wrapped bullet previously still passed because the
bullet text leaked into an untouched sibling paragraph.
- TREE_BRANCH_RE no longer matches an indented/continuation branch
line (dropped the leading `[│ ]*`), so a second-level tree falls
through to verbatim rendering instead of being silently flattened
to one level. Added test_as_file_tree_rejects_deeper_trees to guard it.
RETURNS previously conflated fish's $status exit code with genuine
stdout/printed output, e.g. rm listing "0/1" as if they were print
values rather than exit codes. Rename RETURNS to EXIT STATUS across
all 83 documented functions, and reintroduce RETURNS as a distinct
label reserved for the 15 functions that actually print to stdout.
Update build-manual.py's ENTRY_HEADS to render Exit Status before
Returns, manualtools.py's SECTIONS constant, and AGENTS.md's label
order and label-usage guidance to match. Add two verify-manual.py
regression tests: EXIT STATUS bodies must never contain stray
stdout/printed language, and Returns: must always render after
Exit Status: when both are present. Regenerate docs/fish-config.md.
Every ruled table in the SSOT used one solid rule under the header
except the "Fish Universal Variables" table, which used the other
(per-column, RST-style) convention build-manual.py just learned to
also accept. Two conventions for the same thing with no reason for
the split, so convert the outlier to match the other six.
The parser keeps supporting both — the per-column style stays a
useful fallback for anyone still authoring that way — this just
makes our own SSOT consistent.
_as_ruled_table() only matched a single solid run of dashes under the
header row. The "Fish Universal Variables" table in
07-customization.md uses the other common convention instead: one
dash run per column, gapped the same as the header (RST simple-table
style) — e.g. "------ ----------". That line failed RULE_RE's
whole-line match, so the table still fell through to a code block.
Split the rule line on the same CELL_SPLIT boundary used for data
rows and require every resulting group to be a solid dash run, which
accepts both conventions without adding a second code path.
No SSOT changes needed — the source table was already well-formed,
docs/fish-config.md round-trips unchanged, confirming this is a
site-only fix.
_as_table() only detects tables whose data rows are indented deeper
than a ":"-terminated label. The "Component Reference" tables use a
different convention (header, dashed rule, rows all at the same
indent), so they never matched and fell through to a plain indented
code block on the Starlight site.
Add _as_ruled_table() to recognize that header+rule+rows shape. It
supports N columns, folds word-wrapped continuation lines into the
previous row, and backtick-escapes cells containing "<" or "{" instead
of rejecting the table outright (unlike _as_table's stricter guard,
which those tables would otherwise trip on for angle-bracket
placeholders and brace globs).
Also fixes four ambiguous rows in 07-customization.md where two
columns had collapsed to a single space, making them indistinguishable
from a word-wrapped continuation.
Rename the Starlight site to "Rootiest Fish Config" and switch its
canonical URL from the Cloudflare Pages subdomain to
fish-config.rootiest.fyi (now aliased in Cloudflare). Updates all
references in README, config-help, open-url, and the manual, and
regenerates the concat/man-page artifacts to match.
Function EXAMPLE blocks now render as their own fish fence titled
"Examples" (matching the existing "Usage" title on the Synopsis fence),
triggered by a flat Example: label line mirroring the Synopsis: prefix.
Prose pages get two new generic titling signals in _render_para: a bare
indented path ending in a known extension is titled by its basename, and
a leading "# in <file>" / "# <file>" comment on a shell paragraph is
promoted to the fence title and stripped from the body. This picks up
local.fish/secrets.fish path displays and override examples in
07-customization.md for free, plus a bonus .logging_disabled hit.
10-personalization.md's secrets.fish block gets an explicit "# secrets.fish"
comment to title it the same way. The four local.fish examples keep their
existing descriptive comments rather than a redundant local.fish title.
Swap the Starlight scaffold README for one describing this project's
two-source SSOT and dev/deploy workflow. Give the generated function
synopsis fence a Starlight filename title (`fish title="name.fish"`)
so it reads as a snippet of the function it documents.
Both carry complete headers and are user-facing, but had no # CATEGORY
so generated no entry. Surfaced by the new verify-manual.py warning,
which is exactly what it is there for.
The 8 that still warn are correct exclusions: fast is a self-described
placeholder, the rest are bundled plugin and prompt internals.
Function documentation now comes from functions/*.fish comment headers;
everything else stays in docs/manual/**. Records that split in the three
places a contributor looks:
- AGENTS.md "Documentation Policy" and Coding Convention #4, which now
spells out the full label set and flags CATEGORY as required-to-publish.
- Manual section 11, which pointed readers at docs/manual/ for everything.
- README, same.
The man-page-style comment header above each function in functions/*.fish
becomes the SSOT for that function's documentation. Writing a new function
and documenting it are now the same act.
- manualtools.parse_functions() parses every header carrying a # CATEGORY;
absence of one is the opt-in, keeping bundled-plugin and prompt internals
out of the manual with no exclusion list to maintain.
- build-manual.py generates entries for both --concat and --site, with
**Dependencies:** rendered as links and a **Used by:** reverse index
computed in one pass. Cross-category links are the navigation win.
- docs/manual/05-functions/*.md reduced to frontmatter-only stubs. Every
intro measured zero words, so the category files were pure entry
containers; ordering, titles, and helpKeywords routing are untouched.
- _first_sentence() unwraps the leading hard-wrapped paragraph and skips
the whole Synopsis block, not just its label line. Site cards no longer
truncate mid-clause or show a synopsis as their description.
Verification, per the design spec:
- test_concat_roundtrips_original scoped to sections 0-4 and 6-11. It
guarded a format migration; this is a content migration.
- replaced by structural checks: one entry per categorised function, the
required sections present, every category resolving to a stub with no
stub empty, and every declared dependency resolving to a real function
or a type -q-guarded binary.
- public functions lacking # CATEGORY warn rather than fail, so a new
user-facing function going undocumented stays visible in CI.
24/24 checks pass. 94 entries generated from 94 parsed headers.
Also drops a stale claim from open-url's NOTES: config-help --html calls
xdg-open directly and has never called open-url.
Two-column option and subcommand blocks in the manual were falling through
to the indented-code fallback, rendering as an unhighlighted grey slab on
the site. `_as_table` detects a contiguous, column-aligned indented run and
emits a headerless GFM table instead; anything it cannot prove is tabular
still takes the old path.
15 blocks convert, 20 are correctly left alone. The concat and man-page
outputs are untouched — `prettify` is site-only, and the byte-exact
round-trip test stays green.
Cloudflare Pages reserves a top-level `functions/` directory in the deploy
output for Pages Functions (server-side handlers) and strips it from the
static-asset upload. The wrangler log for run 812 shows the collision
exactly: 159 files uploaded, which is precisely the number of files in
dist/ outside functions/ — all 108 files under it were dropped.
Nothing failed loudly. Astro built all 120 pages, wrangler reported
success, and the site worked under `astro preview`; only the deployed
copy 404'd on every function entry and category index.
Move the generated tree to /reference/ and add a test asserting the site
output never emits a name Pages reserves.
rootiest
Gitea Actions