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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13319-a-markdown-file-s-front-matter-shows-as → main 5 commits fork 3 threads · 3 unresolved
9 files
changed +134
−4
docs/design/areas/code.md +2
| @@ -14,3 +14,5 @@ | ||
| 14 | 14 | A font specimen (`render/font.ts`): `.font-view` sits in a bare card (`card({ extra: "bare" })`, no box of its own); `.font-name` its family heading, `.font-line` one line of sample text, and `.font-s`, `.font-m`, `.font-l` its three sizes. The small size is 14px; the larger two are display sizes, off the UI scale on purpose. |
| 15 | 15 | |
| 16 | 16 | An HTML file's preview (`render/html_preview.ts`): `.html-frame` is a bare sandboxed frame with its own hairline (no card around it) 80vh tall (480px at least, 60vh on a phone). The frame is `color-scheme: light`, so the page inside gets the white canvas it was written for in either theme. |
| 17 | ||
| 18 | - `.front-matter` — a Markdown file's leading `---` block (`frontTable` in `render/markdown.ts`): a `dl.status-rows` of `.status-row` facts above the prose, keys in `--muted-fg`, keys and values wrapping anywhere so a long value never scrolls the page at 360px. |
docs/features/README.md +1
| @@ -267,6 +267,7 @@ Read with the guide page [Your apps](../guide-your-apps.md). | ||
| 267 | 267 | - [](kept-tell.md) |
| 268 | 268 | - [](notebook.md) |
| 269 | 269 | - [](markdown-relative.md) |
| 270 | - [](front-matter.md) | |
| 270 | 271 | - [](terminal-workspace-kinds.md) |
| 271 | 272 | - [](subtitle-shift.md) |
| 272 | 273 | - [](sqlite-view.md) |
docs/features/front-matter.md added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | # Front matter | |
| 2 | ||
| 3 | A Markdown file that opens with a `---` line, flat `key: value` lines, and a closing `---` shows those lines as a small list of facts above its body, in the browser and in the terminal (`src/web/front_matter.ts` is the one parser). | |
| 4 | ||
| 5 | - A key is letters, digits, `_`, `.` or `-` (up to 64), then `:`. A value is the rest of the line; matching quotes around it are dropped. A key with nothing after it is a fact with an empty value. | |
| 6 | - Flat only: no nesting, lists or multi-line values. At most 50 lines. | |
| 7 | - Anything else (a line that is not `key: value`, no closing `---`, an empty block, `---` not on the first line) is not front matter: the file shows as ordinary text. | |
| 8 | - Values are text. A link or an image in one is shown as written, never made live. | |
| 9 | ||
| 10 | Try it: open a `.md` file starting with `---`, `title: Hello`, `---`. |
src/tui/ui/markdown.ts +21 −1
| @@ -16,6 +16,7 @@ import { | ||
| 16 | 16 | highlightLines, |
| 17 | 17 | type Language, |
| 18 | 18 | } from "../../web/highlight.ts"; |
| 19 | import { splitFrontMatter } from "../../web/front_matter.ts"; | |
| 19 | 20 | import { G, type Span } from "../term/screen.ts"; |
| 20 | 21 | import { |
| 21 | 22 | BOLD, |
| @@ -33,7 +34,26 @@ export type Line = Span[]; | ||
| 33 | 34 | |
| 34 | 35 | export function renderMarkdown(src: string, width: number, c: Tokens): Line[] { |
| 35 | 36 | const out: Line[] = []; |
| 36 | const lines = src.replace(/\r\n?/g, "\n").split("\n"); | |
| 37 | const norm = src.replace(/\r\n?/g, "\n"); | |
| 38 | const front = splitFrontMatter(norm); | |
| 39 | if (front !== undefined) { | |
| 40 | const keyWidth = Math.min( | |
| 41 | Math.max(...front.rows.map(([k]) => displayWidth(k))), | |
| 42 | Math.max(1, Math.floor(width / 3)), | |
| 43 | ); | |
| 44 | const valueWidth = Math.max(1, width - keyWidth - 2); | |
| 45 | for (const [k, v] of front.rows) { | |
| 46 | const key = wrap(k, keyWidth); | |
| 47 | const val = wrap(v, valueWidth); | |
| 48 | for (let n = 0; n < Math.max(key.length, val.length); n++) | |
| 49 | out.push([ | |
| 50 | { text: pad(key[n] ?? "", keyWidth) + " ", style: style(c.mutedFg, c.bg) }, | |
| 51 | { text: val[n] ?? "", style: style(c.fg, c.bg) }, | |
| 52 | ]); | |
| 53 | } | |
| 54 | out.push([]); | |
| 55 | } | |
| 56 | const lines = (front === undefined ? norm : front.rest).split("\n"); | |
| 37 | 57 | const body = style(c.fg, c.bg); |
| 38 | 58 | let para: string[] = []; |
| 39 | 59 |
src/web/front_matter.ts added +23
| @@ -0,0 +1,23 @@ | ||
| 1 | /** A Markdown file's leading `---` block of flat `key: value` lines, split from its body. */ | |
| 2 | ||
| 3 | const KEY_LINE = /^([A-Za-z0-9_][A-Za-z0-9_.-]{0,63}):(?:[ \t]+(.*))?$/; | |
| 4 | export const MAX_FRONT_LINES = 50; | |
| 5 | ||
| 6 | /** | |
| 7 | * The rows and the rest of the text, or undefined when the start is anything else (it stays text). | |
| 8 | */ | |
| 9 | export function splitFrontMatter(text: string): { rows: [string, string][]; rest: string } | undefined { | |
| 10 | const lines = text.split("\n"); | |
| 11 | if (lines[0]?.replace(/\r$/, "") !== "---") return undefined; | |
| 12 | const rows: [string, string][] = []; | |
| 13 | for (let i = 1; i < lines.length && i <= MAX_FRONT_LINES + 1; i++) { | |
| 14 | const line = (lines[i] ?? "").replace(/\r$/, ""); | |
| 15 | if (line === "---") { | |
| 16 | return rows.length === 0 ? undefined : { rows, rest: lines.slice(i + 1).join("\n") }; | |
| 17 | } | |
| 18 | const m = KEY_LINE.exec(line); | |
| 19 | if (m === null) return undefined; | |
| 20 | rows.push([m[1] as string, (m[2] ?? "").trim().replace(/^(["'])(.*)\1$/, "$2")]); | |
| 21 | } | |
| 22 | return undefined; | |
| 23 | } |
src/web/render/markdown.ts +10 −3
| @@ -1,10 +1,16 @@ | ||
| 1 | 1 | /** A Markdown file as prose, framed exactly the way a README is. */ |
| 2 | 2 | |
| 3 | import { html } from "../html.ts"; | |
| 3 | import { html, type Html } from "../html.ts"; | |
| 4 | 4 | import { markdownTasks, renderMarkdown } from "../markdown.ts"; |
| 5 | import { splitFrontMatter } from "../front_matter.ts"; | |
| 5 | 6 | import { fileSize } from "../ui.ts"; |
| 6 | 7 | import type { Rendered, RenderInput } from "./renderers.ts"; |
| 7 | 8 | |
| 9 | function frontTable(rows: [string, string][]): Html { | |
| 10 | const body = rows.map(([k, v]) => html`<div class="status-row"><dt>${k}</dt><dd>${v}</dd></div>`); | |
| 11 | return html`<dl class="status-rows front-matter" aria-label="Front matter">${body}</dl>`; | |
| 12 | } | |
| 13 | ||
| 8 | 14 | export function markdown(input: RenderInput): Rendered { |
| 9 | 15 | const slash = input.path.lastIndexOf("/"); |
| 10 | 16 | const repo = |
| @@ -13,11 +19,12 @@ export function markdown(input: RenderInput): Rendered { | ||
| 13 | 19 | : { ...input.repo, dir: slash < 0 ? "" : input.path.slice(0, slash) }; |
| 14 | 20 | const text = new TextDecoder().decode(input.body); |
| 15 | 21 | const lines = text === "" ? 0 : text.replace(/\n$/, "").split("\n").length; |
| 16 | const body = renderMarkdown(text, repo); | |
| 22 | const front = splitFrontMatter(text); | |
| 23 | const body = renderMarkdown(front === undefined ? text : front.rest, repo); | |
| 17 | 24 | const tasks = markdownTasks(body); |
| 18 | 25 | return { |
| 19 | 26 | lines, |
| 20 | content: html`<div class="card prose">${body}</div>`, | |
| 27 | content: html`<div class="card prose">${front === undefined ? "" : frontTable(front.rows)}${body}</div>`, | |
| 21 | 28 | ...(tasks === undefined |
| 22 | 29 | ? {} |
| 23 | 30 | : { |
outdated
Principles 6/7: a fact is a |
src/web/style/content.ts +3
| @@ -532,6 +532,9 @@ img.img-box, .prose img.img-box, .tell-picture.img-box { display: block; width: | ||
| 532 | 532 | |
| 533 | 533 | /* A rendered Markdown blob wears the same frame its source does: one card, |
| 534 | 534 | one path header, and the switch between the two views in it. */ |
| 535 | .front-matter { margin: 0 0 16px; } | |
Non-blocking: the .front-matter rules sit under the comment that describes the Markdown blob frame. Put them after it so the comment still heads what it describes. |
||
| 536 | .front-matter > .status-row > dt { color: var(--muted-fg); overflow-wrap: anywhere; } | |
| 537 | .front-matter > .status-row > dd { overflow-wrap: anywhere; } | |
| 535 | 538 | .rail-facts { margin: 12px 0 0; display: grid; gap: 12px; font-size: 13px; } |
| 536 | 539 | .rail-fact > dt { color: var(--muted-fg); font-size: 12.5px; } |
| 537 | 540 | .rail-fact > dd { margin: 2px 0 0; min-width: 0; overflow-wrap: anywhere; } |
test/render-markdown-front-matter.test.ts added +45
| @@ -0,0 +1,45 @@ | ||
| 1 | /** A Markdown file's leading front matter renders as a small escaped table. */ | |
| 2 | import { describe, expect, test } from "bun:test"; | |
| 3 | import { markdown } from "../src/web/render/markdown.ts"; | |
| 4 | import { splitFrontMatter } from "../src/web/front_matter.ts"; | |
| 5 | ||
| 6 | const render = (text: string): string => | |
| 7 | String(markdown({ path: "n.md", body: new TextEncoder().encode(text), size: text.length, media: "", download: "" }).content); | |
| 8 | ||
| 9 | describe("front matter", () => { | |
| 10 | test("well-formed lines become a list of facts above the body", () => { | |
| 11 | const out = render("---\ntitle: Hello\ntags: \"a, b\"\n---\n# Body\n"); | |
| 12 | expect(out).toContain('<dt>title</dt><dd>Hello</dd>'); | |
| 13 | expect(out).toContain("<dd>a, b</dd>"); | |
| 14 | expect(out.indexOf("front-matter")).toBeLessThan(out.indexOf("<h1")); | |
| 15 | expect(out).not.toContain("title: Hello"); | |
| 16 | }); | |
| 17 | test("values are escaped", () => { | |
| 18 | const out = render("---\ntitle: <script>alert(1)</script>\n---\nx"); | |
| 19 | expect(out).not.toContain("<script>"); | |
| 20 | expect(out).toContain("<script>"); | |
| 21 | }); | |
| 22 | test("malformed front matter stays ordinary text", () => { | |
| 23 | for (const t of ["---\nnot a pair\n---\nx", "---\ntitle: a\nno close", "---\n---\nx", "text\n---\na: b\n---"]) { | |
| 24 | expect(splitFrontMatter(t)).toBeUndefined(); | |
| 25 | expect(render(t)).not.toContain("front-matter"); | |
| 26 | } | |
| 27 | }); | |
| 28 | test("CRLF line endings parse the same", () => { | |
| 29 | expect(splitFrontMatter("---\r\na: b\r\n---\r\nbody")).toEqual({ rows: [["a", "b"]], rest: "body" }); | |
| 30 | }); | |
| 31 | test("quoted values lose one pair of quotes; a key with no value is empty", () => { | |
| 32 | expect(splitFrontMatter("---\na: 'x y'\nb:\nc: \"q\n---\n")?.rows).toEqual([["a", "x y"], ["b", ""], ["c", "\"q"]]); | |
| 33 | }); | |
| 34 | test("more than 50 lines is not front matter", () => { | |
| 35 | const rows = (n: number): string => Array.from({ length: n }, (_, i) => `k${i}: v`).join("\n"); | |
| 36 | expect(splitFrontMatter(`---\n${rows(50)}\n---\n`)?.rows).toHaveLength(50); | |
| 37 | expect(splitFrontMatter(`---\n${rows(51)}\n---\n`)).toBeUndefined(); | |
| 38 | }); | |
| 39 | test("a link or image in a value stays inert text", () => { | |
| 40 | const out = render("---\nhome: [x](http://e.com) \n---\n"); | |
| 41 | expect(out).not.toContain("<a "); | |
| 42 | expect(out).not.toContain("<img"); | |
| 43 | expect(out).toContain("[x](http://e.com)"); | |
| 44 | }); | |
| 45 | }); |
test/tui-markdown-front-matter.test.ts added +19
| @@ -0,0 +1,19 @@ | ||
| 1 | /** The terminal draws front matter as key/value rows, and leaves malformed text alone. */ | |
| 2 | import { expect, test } from "bun:test"; | |
| 3 | import { renderMarkdown } from "../src/tui/ui/markdown.ts"; | |
| 4 | import { theme } from "../src/tui/ui/theme.ts"; | |
| 5 | ||
| 6 | const text = (src: string): string[] => | |
| 7 | renderMarkdown(src, 40, theme("dark").c).map((l) => l.map((s) => s.text).join("")); | |
| 8 | ||
| 9 | test("front matter is key/value rows above the body", () => { | |
| 10 | const out = text("---\ntitle: Hello\ntags: a\n---\nbody"); | |
| 11 | expect(out[0]).toBe("title Hello"); | |
| 12 | expect(out[1]).toBe("tags a"); | |
| 13 | expect(out.join("\n")).not.toContain("---"); | |
| 14 | expect(out).toContain("body"); | |
| 15 | }); | |
| 16 | ||
| 17 | test("malformed front matter stays text", () => { | |
| 18 | expect(text("---\nnot a pair\n---\nx").join("\n")).toContain("not a pair"); | |
| 19 | }); |
new above
offline
This parser is web-only. The terminal's Markdown view still shows raw front matter; share this split and render it in src/tui/ui/markdown.ts.