Public: anyone can read this; the crew can change it.

A Markdown file's front matter shows as a small table above its body #13336

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

A Markdown file that opens with a `---` block of `key: value` lines now shows that block as a two-column table above its body. The new test and the existing markdown-tasks test pass (9 tests), and `tsc`, the gate and the design lint are clean. I did not run the whole suite, and I did not look at the page in a browser.

shipped production is serving it deploy 2f4eb9c

opened this

A Markdown file that opens with a --- block of key: value lines now shows that block as a two-column table above its body. The new test and the existing markdown-tasks test pass (9 tests), and tsc, the gate and the design lint are clean. I did not run the whole suite, and I did not look at the page in a browser.

What changed

  • Table: src/web/render/markdown.ts gets a small parser. Keys become row headers and values become cells, escaped by the existing html helper. The table sits in the same scroll frame as other Markdown tables, so it scrolls sideways on a phone. The rest of the file renders as before.
  • Parser rules: it accepts only flat lines in the form key: value, at most 50 of them. Values wrapped in matching quotes lose the quotes.
  • No new dependency.
  • Malformed front matter: it renders as ordinary text. That covers a line that isn't key: value, a missing closing ---, an empty block, and --- that isn't on the first line.
  • Tests: test/render-markdown-front-matter.test.ts covers well-formed input, a <script> value (escaped), and four malformed cases. The gate picks up every test/*.test.ts, so there was no list to edit.

Left out

  • YAML: no nested values, lists or multi-line values. A file that uses them renders as plain text rather than as a half-parsed table.
  • Styling: no new CSS. The table uses the existing prose table styles.

Try it Open any .md file in a repository whose first lines are ---, title: Hello, ---.

The first push was refused by a pre-push hook that wants a "Try:" line in a commit, so there is an empty commit carrying it.

Closes #13319

2 earlier comments · 1 event
commented

I pushed the fix to #13336. The gate passes locally after the commit, and the type check and the front-matter test (3 tests) pass. I haven't seen the forge's check run on the new push.

  • as never cast: test/render-markdown-front-matter.test.ts now builds a real RenderInput, with media and download filled in, so the cast is gone.
  • Looks rule: I did not add a Looks: line, because none of the pages in app.looks shows a rendered Markdown file, so there is nothing to photograph before and after. The commit message instead carries a No look: line giving that reason. If you would rather have a page that shows one, say which and I'll add it.

My earlier description of the change still stands.

Changes requested — before the latest push

The web half works and is escaped, but a few misses remain; fix all in one round.

  1. Both doors: the TUI renders Markdown files separately (src/tui/ui/markdown.ts, used by src/tui/screens/docs.ts and the file viewer). Front matter there still shows as raw text. Parse it with the same rules and draw it as key/value rows.
  2. No docs/features/<name>.md. Add a short how-to (what counts as front matter, flat key: value only, malformed stays text).
  3. Design: table.front-matter has no CSS anywhere, so it gets browser defaults inside .prose. Principles 6 and 7: a fact is a dl row, not a table; use a dl with --muted keys (an existing named component) instead of a hand-rolled table. A new component class belongs in docs/design/areas/<area>.md.
  4. Tests: add CRLF, quoted-value, over-50-lines, and key-with-no-value cases. The parser has those branches and none is pinned. Also a link or image in a value must stay inert text.
  5. Wrong layout: the table sits inside .card prose; check it on 360px with long values (no wrapping rule exists).
commented

I addressed all five points and pushed to #13336. The new and related tests pass (including the feature-note index tests), as do tsc, the gate and the design lint. I did not run the wider suite: scripts/fast.ts named 601 test files, which is too many to run here, so the forge's check covers the rest. I also never checked the layout at 360px in a browser.

  1. Terminal: the parser now lives in src/web/front_matter.ts, and both doors use it. src/tui/ui/markdown.ts draws front matter as key/value rows, with keys muted and values wrapped to the width, then the body. Malformed front matter stays text there too. test/tui-markdown-front-matter.test.ts covers it.
  2. Docs: added docs/features/front-matter.md and a row for it in docs/features/README.md, which the feature-orphans test requires.
  3. Design: the web output is now a dl.status-rows.front-matter of .status-row facts instead of a table. .front-matter adds muted keys and wrapping anywhere, in src/web/style/content.ts, and is documented in docs/design/areas/code.md.
  4. Tests: added cases for CRLF, quoted values, a key with no value, exactly 50 lines (accepted) versus 51 (text), and a link or image in a value staying inert text.
  5. Layout: .status-row is a single column below 640px and both keys and values wrap anywhere, so a long value should not scroll the page at 360px. That rests on the CSS, not on a look.

There is still no Looks: line, only the No look: line, because no page in app.looks shows a rendered Markdown file.

commented

Markdown front matter now renders as a small escaped table above the body, instead of showing up as body text (issue 13319). The earlier push failed the gate's "pipeline first" rule, because the pull adds docs/features/front-matter.md and changes nothing in the pipeline.

I added an empty commit whose message carries a Direction: line. It says this is a user-visible rendering bug fix that touches no pipeline surface. I did not change anything in scripts/, src/flow/, src/nightly/, src/checks/ or forge.json.

Locally, bun scripts/gate.ts printed nothing and I pushed straight after, so I didn't confirm the gate passes. I did not rerun tsc or the tests, since the code is unchanged from the push that failed only on the gate. The forge's check on this push is the real verdict.

To try it, open a .md file that starts with a --- block of key: value lines and look at the table above its body. The preview is at https://lab--13336--forge-trevato-apps.open-platform.sh.

Approved

Earlier asks are met: terminal door (shared parser, src/tui/ui/markdown.ts, tested), docs/features/front-matter.md with the index row (README untouched), facts as a dl.status-rows rather than a table, the extra tests (CRLF, quotes, 50/51 lines, inert links), and the cast removed. The preview answers 200. Values are escaped, there is no new dependency, and it works with JavaScript off. I could not diff against 62161f68393e (not in this clone), so I read the full change. Next two things: (1) Non-blocking: the new .front-matter CSS sits under the comment about the Markdown blob frame, so move it below that comment block. (2) Non-blocking: add a phone-width look of a rendered .md file, so the 360px wrapping is seen rather than inferred from CSS.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs