fix(docs): render Component Reference tables as real Markdown tables #76

2026-07-26T19:56:38Z

rootiest commented

2026-07-26 19:56:38 +00:00

Why

The "Component Reference" tables in the Customization section (C1–C6) were rendering as plain indented code blocks on the Starlight site instead of real Markdown tables.

Root cause: _as_table() in docs/build-manual.py only detects a table when data rows are indented deeper than a ":"-terminated label (the "Options:" convention used elsewhere). The Component Reference tables use a different, unrelated convention — header row, a solid dashed rule, then data rows all at the same indent — so they never matched and always fell through to the plain code-block fallback.

What changed

Added _as_ruled_table() to recognize the header+rule+rows shape. Unlike _as_table (fixed at 2 columns), it supports N columns.
Word-wrapped continuation lines (a row that splits into a single cell) are folded into the previous row's last column instead of becoming their own broken row.
Cells containing < or { (e.g. <session> placeholders, { } brace globs) are backtick-escaped rather than causing the whole table to be rejected — _as_table's stricter reject-on-</{ guard was left untouched since a test locks in that behavior for its own convention.
A row with a genuinely ambiguous column count (not 1, not matching the header) still bails out to None/code-block, since that's a real source-authoring bug, not something to guess at.
Fixed 4 rows in docs/manual/07-customization.md (C1: du, help config, claude; C4: Done desktop notifications) where two columns had collapsed to a single space, making them ambiguous with a continuation line.
This is site-only — _render_para's output still feeds the man page / config-help path unchanged; test_prettify_is_site_only confirms that invariant still holds.

No user-facing commands, flags, or behavior changed — doc generator only. README audited, no updates needed.

Manual Verification

Run python3 docs/verify-manual.py from docs/ — expect 29/29 passed
Build the Starlight site locally and open the Customization page — confirm all six Component Reference tables (C1–C6) render as real tables, not code blocks
Spot-check the C5 table renders <session>/<win>/<pane> placeholders as inline code, not broken/escaped text
Spot-check the C3 "Autopair" row renders its { } braces as inline code
Confirm the generated man page (docs/fish-config.1) and config-help output for the Customization section are unchanged (still plain indented text, not tables)

## Why The "Component Reference" tables in the Customization section (C1–C6) were rendering as plain indented code blocks on the Starlight site instead of real Markdown tables. Root cause: `_as_table()` in `docs/build-manual.py` only detects a table when data rows are indented *deeper* than a `":"`-terminated label (the "Options:" convention used elsewhere). The Component Reference tables use a different, unrelated convention — header row, a solid dashed rule, then data rows all at the *same* indent — so they never matched and always fell through to the plain code-block fallback. ## What changed - Added `_as_ruled_table()` to recognize the header+rule+rows shape. Unlike `_as_table` (fixed at 2 columns), it supports N columns. - Word-wrapped continuation lines (a row that splits into a single cell) are folded into the previous row's last column instead of becoming their own broken row. - Cells containing `<` or `{` (e.g. `<session>` placeholders, `{ }` brace globs) are backtick-escaped rather than causing the whole table to be rejected — `_as_table`'s stricter reject-on-`<`/`{` guard was left untouched since a test locks in that behavior for its own convention. - A row with a genuinely ambiguous column count (not 1, not matching the header) still bails out to `None`/code-block, since that's a real source-authoring bug, not something to guess at. - Fixed 4 rows in `docs/manual/07-customization.md` (C1: `du`, `help config`, `claude`; C4: `Done desktop notifications`) where two columns had collapsed to a single space, making them ambiguous with a continuation line. - This is **site-only** — `_render_para`'s output still feeds the man page / `config-help` path unchanged; `test_prettify_is_site_only` confirms that invariant still holds. No user-facing commands, flags, or behavior changed — doc generator only. README audited, no updates needed. ## Manual Verification - [x] Run `python3 docs/verify-manual.py` from `docs/` — expect `29/29 passed` - [x] Build the Starlight site locally and open the Customization page — confirm all six Component Reference tables (C1–C6) render as real tables, not code blocks - [x] Spot-check the C5 table renders `<session>`/`<win>`/`<pane>` placeholders as inline code, not broken/escaped text - [x] Spot-check the C3 "Autopair" row renders its `{ }` braces as inline code - [x] Confirm the generated man page (`docs/fish-config.1`) and `config-help` output for the Customization section are unchanged (still plain indented text, not tables)

rootiest added 1 commit 2026-07-26 19:56:39 +00:00

fix(docs): render Component Reference tables as real Markdown tables 05ba0a4f10

_as_table() only detects tables whose data rows are indented deeper
than a ":"-terminated label. The "Component Reference" tables use a
different convention (header, dashed rule, rows all at the same
indent), so they never matched and fell through to a plain indented
code block on the Starlight site.

Add _as_ruled_table() to recognize that header+rule+rows shape. It
supports N columns, folds word-wrapped continuation lines into the
previous row, and backtick-escapes cells containing "<" or "{" instead
of rejecting the table outright (unlike _as_table's stricter guard,
which those tables would otherwise trip on for angle-bracket
placeholders and brace globs).

Also fixes four ambiguous rows in 07-customization.md where two
columns had collapsed to a single space, making them indistinguishable
from a word-wrapped continuation.

rootiest merged commit f2f4d4ef49 into main

2026-07-26 19:58:23 +00:00

rootiest deleted branch docs-ruled-tables

2026-07-26 19:58:23 +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#76