fix(docs): title distro code blocks and fix missed shell highlighting #140

2026-09-09T04:02:54Z

rootiest commented

2026-09-09 04:02:54 +00:00

Summary

Troubleshooting's "Upgrading Fish by distribution" examples carried a leading # Arch / AUR-style comment instead of a Starlight fence title, and several shell examples elsewhere on that page silently fell back to an unhighlighted ```text block. Both are fixed at the root in docs/build-manual.py's site-rendering pass, so the fix applies to the whole generated site, not just this one page.

What changed

New title signal: _render_para now promotes a short leading # Label comment (e.g. # Arch / AUR) to the fence title, alongside the existing filename-comment signal. _label_title distinguishes a label from an explanation — short (≤48 chars, ≤8 words) and not ending in sentence punctuation (.!?;:,) — so a comment like # Turn it off: still stays a literal comment, not a title.
Shared command vocabulary: _is_shell used to check a hardcoded SHELL_HEADS list, so a repo-only command like fish-deps or config-settings was invisible to it even though the exact same vocabulary already exists for codespans' backtick-wrapping. It now reuses that one vocabulary instead of a second, silently drifting one — this is what was making fish-deps install/fish-deps sync render as plain text.
Nested shell blocks: a shell paragraph with its own nested indentation (a for/if/while body) was routed past shell detection entirely by the deeper guard, which exists to protect nested option tables. Shell detection now runs regardless of deeper, fixing the "Erase universal variables" for-loop example (and one other nested block found site-wide, in 13-viewing-this-manual/repo-open).
Updated AGENTS/docs/CLAUDE.md (the docs-pipeline conventions doc, symlinked as docs/CLAUDE.md) to describe the new label-title signal and the shared vocabulary.
Added regression tests for all three fixes to docs/verify-manual.py.

Verification

uv run --with pytest pytest docs/verify-manual.py -q → 76 passed (74 existing + 2 new)
python3 docs/build-manual.py --site then diffed the generated docs/site/src/content/docs/ tree against main's output: only 4 files changed (11-personalization, 12-troubleshooting, 13-viewing-this-manual, reference/miscellaneous/repo-open), every diff a text→fish highlight fix or a comment→title promotion, no regressions.
python3 -m py_compile docs/build-manual.py docs/verify-manual.py

Manual verification checklist

Build the site (cd docs/site && npm run dev or equivalent) and open the Troubleshooting page
Confirm "Upgrading Fish by distribution" shows 4 separate titled terminal-style blocks: "Arch / AUR", "Ubuntu / Debian (PPA)", "Fedora", "macOS"
Confirm "Erase universal variables set by this config" and "Install missing dependencies interactively" / "Or install everything missing..." now render with fish syntax highlighting, not plain text
Spot-check Personalization and "Viewing This Manual" pages for the same kind of fix, and confirm nothing else regressed to plain text

## Summary Troubleshooting's "Upgrading Fish by distribution" examples carried a leading `# Arch / AUR`-style comment instead of a Starlight fence title, and several shell examples elsewhere on that page silently fell back to an unhighlighted ` ```text ` block. Both are fixed at the root in `docs/build-manual.py`'s site-rendering pass, so the fix applies to the whole generated site, not just this one page. ## What changed - **New title signal:** `_render_para` now promotes a short leading `# Label` comment (e.g. `# Arch / AUR`) to the fence title, alongside the existing filename-comment signal. `_label_title` distinguishes a label from an explanation — short (≤48 chars, ≤8 words) and not ending in sentence punctuation (`.!?;:,`) — so a comment like `# Turn it off:` still stays a literal comment, not a title. - **Shared command vocabulary:** `_is_shell` used to check a hardcoded `SHELL_HEADS` list, so a repo-only command like `fish-deps` or `config-settings` was invisible to it even though the exact same vocabulary already exists for `codespans`' backtick-wrapping. It now reuses that one vocabulary instead of a second, silently drifting one — this is what was making `fish-deps install`/`fish-deps sync` render as plain text. - **Nested shell blocks:** a shell paragraph with its own nested indentation (a `for`/`if`/`while` body) was routed past shell detection entirely by the `deeper` guard, which exists to protect nested option tables. Shell detection now runs regardless of `deeper`, fixing the "Erase universal variables" for-loop example (and one other nested block found site-wide, in `13-viewing-this-manual`/`repo-open`). - Updated `AGENTS/docs/CLAUDE.md` (the docs-pipeline conventions doc, symlinked as `docs/CLAUDE.md`) to describe the new label-title signal and the shared vocabulary. - Added regression tests for all three fixes to `docs/verify-manual.py`. ## Verification - `uv run --with pytest pytest docs/verify-manual.py -q` → 76 passed (74 existing + 2 new) - `python3 docs/build-manual.py --site` then diffed the generated `docs/site/src/content/docs/` tree against `main`'s output: only 4 files changed (`11-personalization`, `12-troubleshooting`, `13-viewing-this-manual`, `reference/miscellaneous/repo-open`), every diff a `text`→`fish` highlight fix or a comment→title promotion, no regressions. - `python3 -m py_compile docs/build-manual.py docs/verify-manual.py` ## Manual verification checklist - [x] Build the site (`cd docs/site && npm run dev` or equivalent) and open the Troubleshooting page - [x] Confirm "Upgrading Fish by distribution" shows 4 separate titled terminal-style blocks: "Arch / AUR", "Ubuntu / Debian (PPA)", "Fedora", "macOS" - [x] Confirm "Erase universal variables set by this config" and "Install missing dependencies interactively" / "Or install everything missing..." now render with fish syntax highlighting, not plain text - [x] Spot-check Personalization and "Viewing This Manual" pages for the same kind of fix, and confirm nothing else regressed to plain text

rootiest added 1 commit 2026-09-09 04:02:55 +00:00

fix(docs): title distro code blocks and fix missed shell highlighting 47074821c0

Troubleshooting's "Upgrading Fish by distribution" examples carried a
leading "# Arch / AUR"-style comment instead of a Starlight fence title.
Generalize the existing filename-comment title signal to any short
label comment (excluded when it reads as a sentence, e.g. ends in
punctuation) so it titles the block and is stripped from the body.

Also fixes two cases where shell examples fell back to an unhighlighted
```text block instead of ```fish:
- `_is_shell` only recognized a hardcoded command list, so any repo-only
  command (fish-deps, config-settings, ...) was invisible to it even
  though the same vocabulary already exists for codespans wrapping.
  Now `_is_shell` reuses that one vocabulary instead of a second,
  drifting one.
- A shell paragraph with its own nested indentation (a for/if/while
  body) was routed past shell detection entirely by the `deeper` guard,
  which exists for nested option tables. Shell detection now runs
  regardless of `deeper`.

rootiest added the Kind/Bug Area/Docs labels 2026-09-09 04:03:20 +00:00

rootiest added 1 commit 2026-09-09 04:43:34 +00:00

docs: drop hardcoded sub-category counts from C1-C6 prose 664c8bf7ee

Both counts ("two to six", "25 in total") would silently go stale if a
sub-category is ever added or removed. Reworded to "several" so the
prose no longer needs a manual update alongside the guard registry.

rootiest merged commit 8e4b719425 into main

2026-09-09 04:43:51 +00:00

rootiest deleted branch docs/troubleshooting-codeblock-titles

2026-09-09 04:43:51 +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#140