fix(docs): reformat Prompt and Theme section and fix MDX code-block bug #119

2026-08-25T05:28:50Z

rootiest commented

2026-08-25 05:28:50 +00:00

Summary

Requested as a QA/formatting pass on Customization → Prompt and Theme, but turned up a real generator bug with wider reach.

Root cause found: build-manual.py's fallback for any block it can't classify as shell/table/tree used to emit plain 4-space markdown indentation. That only renders as a code block in plain Markdown — MDX (used for any page that also contains an <Aside> or <FileTree>) has no indented-code-block syntax, so it silently rendered those blocks as squashed, whitespace-collapsed paragraph text. That's exactly the garbled Docker-context example pasted in the original report — it wasn't a badly-styled code block, it wasn't a code block at all.

Confirmed 5 live pages hit this: 07-customization.mdx, both 08-components-reference C5/C6 pages, 12-troubleshooting.mdx, and 13-viewing-this-manual.mdx.

Fix scope (per discussion): fixed the shared fallback for every page rather than only the 5 broken ones, since the alternative (page-specific patching) would leave the same landmine for any function-reference page the moment someone adds an Aside/FileTree to it later. As a side effect, ~100+ ordinary reference pages' Arguments:/Exit Status: blocks now render as proper chromed code blocks instead of a bare grey slab (no functional change there, just nicer, consistent styling).

Known minor rough edge: on the C5 logging reference page, two single-line list-continuation fragments (list items indented past 4 spaces per normal Markdown continuation rules) now render as small standalone code-boxed fragments instead of flowing text. This is a pre-existing prettify() heuristic limitation (it can't yet tell "list continuation" from "code block" indentation) — not new, just a different-looking symptom of it. Flagging for a possible follow-up rather than fixing here, since fixing it properly means teaching the block-detection loop about list continuations.

Content fixes (verified against source)

Starship: documented the missing C3-override gate (the wrapper needs starship in PATH and C3 enabled, not just PATH) and the blank-line-before-prompt behavior.
Fallback prompt: reordered the segment legend to match actual render order, added the missing O (operator-pending) vi-mode state, and noted the background-job line that appears between the two prompt rows.
Right prompt: rewrote the Docker-context example — it's independent of exit status, which the old three-row example didn't make clear (and, per the MDX bug above, wasn't rendering as three rows at all).
FZF: fixed the file location (conf.d/theme.fish, not integrations/fzf.fish) and replaced the incomplete color summary with the full, accurate color table.
Catppuccin theme switching: fixed fish_config theme save "Catppuccin Latte" → fish_config theme choose "Catppuccin Latte" — save would have overwritten the Latte theme file with your currently-active colors instead of switching to it.
Fixed a stray `---` (backtick-wrapped) at the end of the file that should have been a plain --- like every other manual file.

Changes

docs/build-manual.py: _render_para's fallback now emits a fenced ```text block instead of indentation; added fish_config to SHELL_HEADS so theme-switch examples get shell highlighting.
docs/manual/07-customization.md: content fixes and reformatting described above (ASCII prompt layout → fenced block; segment legends and FZF colors → real tables).
docs/verify-manual.py: updated test_prettify_leaves_reference_tables_alone for the new fenced-not-indented behavior; added test_prettify_fallback_fences_instead_of_indenting to lock in the fix.

docs/fish-config.md is intentionally left unregenerated — CI regenerates and auto-commits it from docs/manual/** on push to main, so test_concat_roundtrips_original is expected to be the one red test locally until CI's pipeline runs.

Test plan

python3 docs/verify-manual.py — 55/56 passed (the one expected failure is test_concat_roundtrips_original, explained above)
python3 docs/build-manual.py --site && npx astro build in docs/site — 154 pages built, all internal links valid
Inspected the built HTML for the Prompt/Theme section and all 5 previously-broken pages — confirmed real <pre>/Expressive-Code blocks and <table>s where expected, no more squashed paragraphs
Confirmed docs/manual/07-customization.md's content still reads correctly in the plain-text --concat output (used for the offline manual/man page)

## Summary Requested as a QA/formatting pass on Customization → Prompt and Theme, but turned up a real generator bug with wider reach. **Root cause found**: `build-manual.py`'s fallback for any block it can't classify as shell/table/tree used to emit plain 4-space markdown indentation. That only renders as a code block in plain Markdown — MDX (used for any page that also contains an `<Aside>` or `<FileTree>`) has no indented-code-block syntax, so it silently rendered those blocks as squashed, whitespace-collapsed paragraph text. That's exactly the garbled Docker-context example pasted in the original report — it wasn't a badly-styled code block, it wasn't a code block at all. Confirmed 5 live pages hit this: `07-customization.mdx`, both `08-components-reference` C5/C6 pages, `12-troubleshooting.mdx`, and `13-viewing-this-manual.mdx`. **Fix scope** (per discussion): fixed the shared fallback for every page rather than only the 5 broken ones, since the alternative (page-specific patching) would leave the same landmine for any function-reference page the moment someone adds an `Aside`/`FileTree` to it later. As a side effect, ~100+ ordinary reference pages' `Arguments:`/`Exit Status:` blocks now render as proper chromed code blocks instead of a bare grey slab (no functional change there, just nicer, consistent styling). **Known minor rough edge**: on the C5 logging reference page, two single-line list-continuation fragments (list items indented past 4 spaces per normal Markdown continuation rules) now render as small standalone code-boxed fragments instead of flowing text. This is a pre-existing `prettify()` heuristic limitation (it can't yet tell "list continuation" from "code block" indentation) — not new, just a different-looking symptom of it. Flagging for a possible follow-up rather than fixing here, since fixing it properly means teaching the block-detection loop about list continuations. ## Content fixes (verified against source) - **Starship**: documented the missing C3-override gate (the wrapper needs starship in PATH *and* C3 enabled, not just PATH) and the blank-line-before-prompt behavior. - **Fallback prompt**: reordered the segment legend to match actual render order, added the missing `O` (operator-pending) vi-mode state, and noted the background-job line that appears between the two prompt rows. - **Right prompt**: rewrote the Docker-context example — it's independent of exit status, which the old three-row example didn't make clear (and, per the MDX bug above, wasn't rendering as three rows at all). - **FZF**: fixed the file location (`conf.d/theme.fish`, not `integrations/fzf.fish`) and replaced the incomplete color summary with the full, accurate color table. - **Catppuccin theme switching**: fixed `fish_config theme save "Catppuccin Latte"` → `fish_config theme choose "Catppuccin Latte"` — `save` would have overwritten the Latte theme file with your currently-active colors instead of switching to it. - Fixed a stray `` `---` `` (backtick-wrapped) at the end of the file that should have been a plain `---` like every other manual file. ## Changes - `docs/build-manual.py`: `_render_para`'s fallback now emits a fenced ` ```text ` block instead of indentation; added `fish_config` to `SHELL_HEADS` so theme-switch examples get shell highlighting. - `docs/manual/07-customization.md`: content fixes and reformatting described above (ASCII prompt layout → fenced block; segment legends and FZF colors → real tables). - `docs/verify-manual.py`: updated `test_prettify_leaves_reference_tables_alone` for the new fenced-not-indented behavior; added `test_prettify_fallback_fences_instead_of_indenting` to lock in the fix. `docs/fish-config.md` is intentionally left unregenerated — CI regenerates and auto-commits it from `docs/manual/**` on push to main, so `test_concat_roundtrips_original` is expected to be the one red test locally until CI's pipeline runs. ## Test plan - [x] `python3 docs/verify-manual.py` — 55/56 passed (the one expected failure is `test_concat_roundtrips_original`, explained above) - [x] `python3 docs/build-manual.py --site && npx astro build` in `docs/site` — 154 pages built, all internal links valid - [x] Inspected the built HTML for the Prompt/Theme section and all 5 previously-broken pages — confirmed real `<pre>`/Expressive-Code blocks and `<table>`s where expected, no more squashed paragraphs - [x] Confirmed `docs/manual/07-customization.md`'s content still reads correctly in the plain-text `--concat` output (used for the offline manual/man page)

rootiest added 1 commit 2026-08-25 05:28:50 +00:00

fix(docs): reformat Prompt and Theme section and fix MDX code-block bug 9969f43ba3

Verified every claim in the Prompt and Theme section against the actual
source and corrected several inaccuracies: the Starship wrapper's missing
C3 gate, the fallback prompt's vi-mode states and segment order, the FZF
theme's real location (conf.d/theme.fish, not integrations/fzf.fish) and
color set, and the Catppuccin theme-switch example using the wrong
fish_config subcommand (choose, not save). The right-prompt Docker-context
example was rewritten to show that it's independent of exit status.

While reformatting, found that any block build-manual.py couldn't classify
as shell/table/tree fell back to plain 4-space markdown indentation, which
silently renders as squashed, unreadable paragraph text on any page that
also contains an <Aside> or <FileTree> — MDX has no indented-code-block
syntax, unlike plain Markdown. This affected 07-customization.mdx plus four
other pages. Fixed the fallback to emit a fenced ```text block instead,
since fences work in both MDX and plain Markdown; this also gives every
affected block Starlight's normal code-block styling instead of a bare grey
slab.

docs/fish-config.md is intentionally left stale here — CI regenerates and
auto-commits it from docs/manual/** on push to main.

rootiest added 1 commit 2026-08-25 05:49:29 +00:00

Merge branch 'main' into docs/customization-prompt-theme-formatting d44dbd3564

rootiest merged commit e97b3ee6ab into main

2026-08-25 05:49:40 +00:00

rootiest deleted branch docs/customization-prompt-theme-formatting

2026-08-25 05:49:41 +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#119