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

2026-07-26T09:03:37Z

rootiest commented

2026-07-26 09:03:37 +00:00

Follow-ups to the Starlight migration (PR #74):

Replace the generic astro create --template starlight scaffold README
under docs/site/ with one describing this project's two-source SSOT
and dev/deploy workflow.
Adopt Starlight's filename title
convention for fenced code blocks across the generated site:
- Function reference pages: the Synopsis fence is now titled "Usage"
  and the EXAMPLE block gets its own fence titled "Examples"
  (build-manual.py's _prettify_block, triggered by a flat Example:
  label line mirroring the existing Synopsis: handling), propagating
  to all ~96 generated function reference pages.
- Prose pages (docs/manual/**) pick up two new generic 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. This
  titles the local.fish/secrets.fish path displays and override
  examples in 07-customization.md (plus a bonus .logging_disabled
  hit) and the secrets.fish example in 10-personalization.md, with
  no changes needed to docs/manual/**.md beyond the existing
  indentation — test_prettify_is_site_only still forbids literal
  fences in the SSOT.

Manual Verification

python3 docs/verify-manual.py → 25/25 passed, same pre-existing
8-function CATEGORY warning, nothing else.
python3 docs/build-manual.py --site, then check a generated
function page (e.g. /reference/git-and-version-control/branch/) —
the synopsis fence should show a Usage tab and, for functions with
an EXAMPLE, a separate Examples fence below it.
Check /reference/customization/ — the local.fish/secrets.fish
path tree and the override examples should show filename tabs
(local.fish, secrets.fish, .logging_disabled).
Check /reference/personalization/ — the secrets.fish example
block should show a secrets.fish tab; the four local.fish
examples intentionally keep their descriptive comments instead
(# CDPATH — …, # SSH shortcuts, etc.) rather than a redundant
local.fish title repeated four times.
Open docs/site/README.md and confirm it describes this repo, not
the Starlight starter kit.

Follow-ups to the Starlight migration (PR #74): - Replace the generic `astro create --template starlight` scaffold README under `docs/site/` with one describing this project's two-source SSOT and dev/deploy workflow. - Adopt Starlight's [filename title](https://starlight.astro.build/guides/authoring-content/#frames-and-titles) convention for fenced code blocks across the generated site: - Function reference pages: the Synopsis fence is now titled `"Usage"` and the EXAMPLE block gets its own fence titled `"Examples"` (`build-manual.py`'s `_prettify_block`, triggered by a flat `Example:` label line mirroring the existing `Synopsis:` handling), propagating to all ~96 generated function reference pages. - Prose pages (`docs/manual/**`) pick up two new generic 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. This titles the `local.fish`/`secrets.fish` path displays and override examples in `07-customization.md` (plus a bonus `.logging_disabled` hit) and the `secrets.fish` example in `10-personalization.md`, with no changes needed to `docs/manual/**.md` beyond the existing indentation — `test_prettify_is_site_only` still forbids literal fences in the SSOT. ## Manual Verification - [x] `python3 docs/verify-manual.py` → `25/25 passed`, same pre-existing 8-function CATEGORY warning, nothing else. - [x] `python3 docs/build-manual.py --site`, then check a generated function page (e.g. `/reference/git-and-version-control/branch/`) — the synopsis fence should show a `Usage` tab and, for functions with an EXAMPLE, a separate `Examples` fence below it. - [ ] Check `/reference/customization/` — the `local.fish`/`secrets.fish` path tree and the override examples should show filename tabs (`local.fish`, `secrets.fish`, `.logging_disabled`). - [x] Check `/reference/personalization/` — the `secrets.fish` example block should show a `secrets.fish` tab; the four `local.fish` examples intentionally keep their descriptive comments instead (`# CDPATH — …`, `# SSH shortcuts`, etc.) rather than a redundant `local.fish` title repeated four times. - [x] Open `docs/site/README.md` and confirm it describes this repo, not the Starlight starter kit.

rootiest added 1 commit 2026-07-26 09:03:38 +00:00

docs(site): replace starter README and title synopsis fences e20cff41d4

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.

rootiest added 1 commit 2026-07-26 09:27:54 +00:00

docs(site): title Examples fences and auto-title file-scoped snippets 625a58fa9f

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.

rootiest changed title from ~~docs(site): replace starter README and title synopsis fences~~ to docs(site): replace starter README and title code fences throughout the manual

2026-07-26 09:28:16 +00:00

rootiest merged commit 5c21788c8f into main

2026-07-26 09:29:26 +00:00

rootiest deleted branch docs-option-tables

2026-07-26 09:29:27 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rootiest/fish-config#75