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

scout/forge:scout/13319-a-markdown-file-s-front-matter-shows-as → main 5 commits fork 3 threads · 3 unresolved

  • Merged. scout/13319-a-markdown-file-s-front-matter-shows-as was merged into main as 867ab48.

Review

Sign in to review this change.
9 files changed +134 −4
docs/design/areas/code.md +2
@@ -14,3 +14,5 @@
1414 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.
1515
1616 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).
267267 - [A half-written tell is kept](kept-tell.md)
268268 - [Jupyter notebooks](notebook.md)
269269 - [Markdown relative images and links](markdown-relative.md)
270 - [Markdown front matter as a list of facts](front-matter.md)
270271 - [Notebooks, JSON Lines and logs in the terminal](terminal-workspace-kinds.md)
271272 - [Shift a subtitle file](subtitle-shift.md)
272273 - [SQLite files as tables](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 {
1616 highlightLines,
1717 type Language,
1818 } from "../../web/highlight.ts";
19 import { splitFrontMatter } from "../../web/front_matter.ts";
1920 import { G, type Span } from "../term/screen.ts";
2021 import {
2122 BOLD,
@@ -33,7 +34,26 @@ export type Line = Span[];
3334
3435 export function renderMarkdown(src: string, width: number, c: Tokens): Line[] {
3536 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");
3757 const body = style(c.fg, c.bg);
3858 let para: string[] = [];
3959
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 @@
11 /** A Markdown file as prose, framed exactly the way a README is. */
22
3 import { html } from "../html.ts";
3 import { html, type Html } from "../html.ts";
44 import { markdownTasks, renderMarkdown } from "../markdown.ts";
5 import { splitFrontMatter } from "../front_matter.ts";
56 import { fileSize } from "../ui.ts";
67 import type { Rendered, RenderInput } from "./renderers.ts";
78
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
814 export function markdown(input: RenderInput): Rendered {
outdated

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.

915 const slash = input.path.lastIndexOf("/");
1016 const repo =
@@ -13,11 +19,12 @@ export function markdown(input: RenderInput): Rendered {
1319 : { ...input.repo, dir: slash < 0 ? "" : input.path.slice(0, slash) };
1420 const text = new TextDecoder().decode(input.body);
1521 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);
1724 const tasks = markdownTasks(body);
1825 return {
1926 lines,
20 content: html`<div class="card prose">${body}</div>`,
27 content: html`<div class="card prose">${front === undefined ? "" : frontTable(front.rows)}${body}</div>`,
2128 ...(tasks === undefined
2229 ? {}
2330 : {
outdated

Principles 6/7: a fact is a dl row, not a table. front-matter has no styling, so it renders with browser defaults. Use a dl and an existing component, and wrap long values for a 360px phone.

src/web/style/content.ts +3
@@ -532,6 +532,9 @@ img.img-box, .prose img.img-box, .tell-picture.img-box { display: block; width:
532532
533533 /* A rendered Markdown blob wears the same frame its source does: one card,
534534 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; }
535538 .rail-facts { margin: 12px 0 0; display: grid; gap: 12px; font-size: 13px; }
536539 .rail-fact > dt { color: var(--muted-fg); font-size: 12.5px; }
537540 .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("&lt;script&gt;");
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) ![i](http://e.com/a.png)\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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs