feat(docs): Starlight asides and file-tree conversions (site-build-only) #78

2026-07-27T01:30:04Z

rootiest commented

2026-07-27 01:30:04 +00:00

Summary

Converts closed-set LABEL: SSOT paragraphs (NOTE/IMPORTANT/TIP/HINT/WARNING/CAUTION/DANGER) into Starlight <Aside> components, and the one ASCII file tree in docs/manual/10-personalization.md into a Starlight <FileTree> component — both only at site-build time (build_site()), never touching the man-page/config-help/concat pipeline.
Pages that end up containing either component are promoted from .md to .mdx with the needed import line; everything else stays .md.
docs/manual/07-customization.md's Notes: list rewritten to a NOTE: callout paragraph as the first real-world usage.
New conventions documented in AGENTS/AGENTS.md (Documentation Policy section).

Implementation notes

7-task plan executed via subagent-driven development; each task individually implemented, tested, and task-reviewed clean.
Final whole-branch review (opus) found the site-only architectural boundary sound (verified 3 independent ways: test_prettify_is_site_only guard, all 3 prettify() call sites confined to build_site(), and all 17 generated .mdx pages compiled through a real @mdx-js/mdx + remark-gfm parser) but flagged two Important findings, both fixed and independently re-verified before this PR:
1. A regression test used whole-page substring checks that would still pass even if a bug truncated the <Aside> and let bullets escape it — now scoped to the aside's interior text.
2. The FileTree detector's branch-line regex accepted second-level (nested) lines and silently flattened them instead of rejecting the tree as documented ("single-level nesting only") — the regex no longer matches nested lines, and a regression test locks this in.
43/43 tests pass (python3 docs/verify-manual.py).
README.md audited — no update needed (no new user-facing command, flag, or variable; this is purely internal to the docs-generation pipeline).

Manual Verification

Run python3 docs/verify-manual.py and confirm 43/43 passed, 0 FAIL
Run the Starlight site build (docs/site) and visually confirm:
- 07-customization renders its NOTE: paragraph as a Starlight <Aside> with all 4 bullets inside it
- 10-personalization renders its file listing as a Starlight <FileTree>
- 11-viewing-this-manual renders correctly as an aside
Confirm the man page (docs/fish-config.1) and config-help output show the same three sections as plain, unconverted text — no <Aside/<FileTree/literal component markup anywhere
Spot-check a couple of unrelated .md pages in the generated site still render as .md (not wrongly promoted to .mdx)

## Summary - Converts closed-set `LABEL:` SSOT paragraphs (`NOTE`/`IMPORTANT`/`TIP`/`HINT`/`WARNING`/`CAUTION`/`DANGER`) into Starlight `<Aside>` components, and the one ASCII file tree in `docs/manual/10-personalization.md` into a Starlight `<FileTree>` component — both **only** at site-build time (`build_site()`), never touching the man-page/`config-help`/concat pipeline. - Pages that end up containing either component are promoted from `.md` to `.mdx` with the needed import line; everything else stays `.md`. - `docs/manual/07-customization.md`'s `Notes:` list rewritten to a `NOTE:` callout paragraph as the first real-world usage. - New conventions documented in `AGENTS/AGENTS.md` (Documentation Policy section). ## Implementation notes - 7-task plan executed via subagent-driven development; each task individually implemented, tested, and task-reviewed clean. - Final whole-branch review (opus) found the site-only architectural boundary sound (verified 3 independent ways: `test_prettify_is_site_only` guard, all 3 `prettify()` call sites confined to `build_site()`, and all 17 generated `.mdx` pages compiled through a real `@mdx-js/mdx` + `remark-gfm` parser) but flagged two Important findings, both fixed and independently re-verified before this PR: 1. A regression test used whole-page substring checks that would still pass even if a bug truncated the `<Aside>` and let bullets escape it — now scoped to the aside's interior text. 2. The `FileTree` detector's branch-line regex accepted second-level (nested) lines and silently flattened them instead of rejecting the tree as documented ("single-level nesting only") — the regex no longer matches nested lines, and a regression test locks this in. - 43/43 tests pass (`python3 docs/verify-manual.py`). - README.md audited — no update needed (no new user-facing command, flag, or variable; this is purely internal to the docs-generation pipeline). ## Manual Verification - [x] Run `python3 docs/verify-manual.py` and confirm `43/43 passed`, `0 FAIL` - [x] Run the Starlight site build (`docs/site`) and visually confirm: - [x] `07-customization` renders its `NOTE:` paragraph as a Starlight `<Aside>` with all 4 bullets inside it - [x] `10-personalization` renders its file listing as a Starlight `<FileTree>` - [x] `11-viewing-this-manual` renders correctly as an aside - [x] Confirm the man page (`docs/fish-config.1`) and `config-help` output show the same three sections as **plain, unconverted text** — no `<Aside`/`<FileTree`/literal component markup anywhere - [x] Spot-check a couple of unrelated `.md` pages in the generated site still render as `.md` (not wrongly promoted to `.mdx`)

rootiest added 8 commits 2026-07-27 01:30:05 +00:00

feat(docs): add _as_aside detector for LABEL: callout paragraphs 413b8d8fa1

feat(docs): render flat LABEL: paragraphs as Starlight asides in prettify() d972de3df5

feat(docs): add _as_file_tree detector for box-drawing trees 690bfd64d0

test(docs): forbid Aside, FileTree, and ::: markers in the manual SSOT 6ac647e0c1

docs(customization): convert Notes: list to a NOTE: callout paragraph 819a3b1541

feat(docs): promote pages with asides or file trees to .mdx 1c671d71ac

chore(docs): regenerate manual and man page fe59a7c22c

fix(docs): scope aside regression test to its contents, reject nested file trees ef384b9c7c

- 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.

rootiest merged commit 7a0e1f0930 into main

2026-07-27 01:39:34 +00:00

rootiest deleted branch starlight-asides-and-filetree

2026-07-27 01:39:35 +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#78