5 Commits

Include renames

Author	SHA1	Message	Date
rootiest	6cd0de7ccf	fix(docs-site): publish function pages under /reference/ ... 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.	2026-07-26 00:48:26 -04:00
rootiest	ab2f03213b	feat(docs-site): syntax-highlight examples and restyle the site ... The manual is authored man-page style: every synopsis, example, option table, and description sits in one 4-space-indented block. On the site that renders as a single unhighlighted grey slab, because an indented block declares no language. Split each block into its paragraphs at site-build time and classify them: synopsis and shell examples become ```fish fences, descriptions become real prose, and column-aligned reference tables keep their indentation. 175 blocks now highlight; the 412 lines of genuine tables are left alone. The transform is site-only. docs/manual/** keeps the indented form the pandoc man-page pipeline and config-help depend on, and a test enforces that no fence is ever written back to the SSOT. Also: - Point Expressive Code at the bundled Catppuccin Mocha/Latte themes so code blocks match the palette in catppuccin.css. - Build the functions sidebar group explicitly. `autogenerate` labelled it with the raw directory slug and republished the directory index as a child of the group it already titled, producing the duplicate "Functions Reference" row. - Skip `Synopsis:` lines when deriving card descriptions; they restated the calling convention the card already shows as its title. - Widen the palette: tinted heading levels, inline code, links, card hover accents, aside accents, and table headers. Fixes a bug where _split_entries stripped the leading indentation of an entry's first line, detaching `Synopsis:` from the block it opens.	2026-07-26 00:12:33 -04:00
rootiest	a4054de4f6	feat(docs): generate Starlight content from the manual tree ... Add build_manual.build_site(), which walks docs/manual and emits the Astro Starlight content collection: plain pages copied with pipeline-only frontmatter (man/site/manTitle/helpKeywords) stripped, and *-functions/ category files exploded into one page per function plus a CardGrid/LinkCard overview. Writes src/sidebar.json for astro.config.mjs to import. Wires --site alongside the existing --concat flag. Fixes two latent defects found while building the real site against the strict content.config.ts schema: - _split_entries now tracks fenced code blocks (like manualtools.shift_headings does) so a `## ` inside a fence can't be mistaken for an entry boundary. - LinkCard title/description are escaped for JSX attribute context, since shell synopses routinely contain `<placeholder>` angle brackets that would otherwise open unterminated MDX/JSX parsing. Also fixes the generated sidebar shape for the functions category: Starlight 0.39+ dropped support for a bare `autogenerate` sibling of `label` on a top-level group, so the autogenerate config now nests inside `items`. Verified with a full `astro build` (temporarily pointing astro.config.mjs at the generated sidebar.json, then reverted since replacing that config is a later task's deliverable): 120 pages built cleanly, no content-collection/frontmatter/MDX errors.	2026-07-25 22:44:28 -04:00
rootiest	beb89e406a	fix(docs): move pandoc metadata out of index.md frontmatter ... index.md is both the man-page LANDING section and a Starlight content page. Astro errors on any frontmatter key outside the fixed man/site/manTitle/helpKeywords schema, so folding the source fish-config.md pandoc header (title/section/header/date/author) onto index.md under a fifth "pandoc" key would break the docs-site build the moment it's scaffolded. Relocate that block to docs/manual/_pandoc.yml: a plain, fence-free YAML file that Astro content collections ignore (leading underscore). split-manual.py now extracts it as raw text (no yaml.safe_load/ safe_dump round-trip) so build-manual.py's --concat re-emits it byte-for-byte instead of merely "verbatim" in comment only. Also guard build_concat against a manual/ tree with no _pandoc.yml/index.md, removing the unconditional index.md parse that previously raised FileNotFoundError on such a tree. Regenerated docs/manual/ via split-manual.py; concat output remains byte-identical to the pre-migration docs/fish-config.md.	2026-07-25 21:52:54 -04:00
rootiest	63e71ac9dd	feat(docs): generate fish-config.md from the manual tree ... Adds docs/build-manual.py (--concat) and a round-trip test in verify-manual.py that reproduces the pre-migration fish-config.md exactly from docs/manual/. Fixes found by the round-trip check, applied in split-manual.py and re-run to regenerate docs/manual/: - NAME/SYNOPSIS/TABLE OF CONTENTS had no sidebar.order, so they sorted after every numbered section instead of interleaving with DESCRIPTION in original document order. All manual pages now get sidebar.order from a single position counter matching source order. - split_h1/split_h2 used .strip() on section bodies, which also ate leading indentation on the first body line, corrupting the 4-space indented code blocks that open SYNOPSIS and TABLE OF CONTENTS. - The source's leading pandoc metadata block (title/section/header/ date/author) was discarded entirely by the splitter. It's now parsed off via manualtools.parse and stashed on index.md under a "pandoc" key; build-manual.py re-emits it verbatim ahead of the first heading.	2026-07-25 21:39:48 -04:00