Skip to content

docs: regenerate WALKTHROUGH.md as plain markdown, and declare prettier - #81

Merged
philoserf merged 1 commit into
mainfrom
docs/plain-markdown-walkthrough
Sep 16, 2026
Merged

philoserf merged 1 commit into
mainfrom
docs/plain-markdown-walkthrough

Conversation

@philoserf

Copy link
Copy Markdown
Owner

Two coupled changes: regenerating the walkthrough without showboat is what exposed the formatting gap, so they land together.

The document

code-walkthrough no longer builds this file with showboat, so it is ordinary markdown now.

before after
lines 1,429 1,096
fenced blocks 94 41
captured output vs prose 1.8× —

The old form paired every snippet with a captured output block, and 39 of its 47 commands were sed ranges whose only assertion was that some text still matched a file. Snippets are now quoted inline and labelled `file` — `symbol` rather than by line range.

Dropping showboat also removed constraints that were shaping content, not just formatting:

  • What the tests cover shows real bun test output instead of a grep of test names — that was a workaround for verify breaking on non-deterministic output.
  • Architecture is a table instead of a shell loop — a workaround for verify breaking on repo-tracking output.
  • The export demo no longer needs a frozen timestamp.

Since nothing checks this document any more, fidelity was verified rather than assumed: every labelled ts block was diffed against the source file it names — 271 substantive lines, 0 mismatches.

Prettier

That check initially failed, which is why this PR also adds prettier.

The user-level auto-format hook runs prettier on any markdown it sees. This repo declared no prettier config, so prettier used its defaults — including embeddedLanguageFormatting: "auto", which rewrote quoted TypeScript into double quotes at width 80, against this repo's Biome style of single quotes at width 100. Three snippets stopped matching their source.

Biome 2.5 does not process markdown at all (Checked 0 files), so this is not a redundant second formatter — it is the only tool that can do this job. Prettier is now a declared devDependency wired into check, check:ci and format, scoped to **/*.md so it never fights Biome over TypeScript or JSON.

  • .prettierrc.json — proseWrap: preserve, embeddedLanguageFormatting: off. The second is load-bearing, not stylistic.
  • .prettierignore — excludes .issues/, which is ignored through the global core.excludesfile rather than this repo's .gitignore, so git hides it and prettier does not. Without this, check:ci fails on agent working notes that never ship.

Markdown drift now fails the pre-push hook like any other formatting. Verified by appending bad whitespace to README.md and confirming check:ci blocked, then restoring it.

The same gap exists across the workspace and is now tracked: 14 repos with no prettier at all, and 7 that run it with no config.

Noise in the diff

THEORY.md's 50 changed lines are prettier normalizing *emphasis* to _emphasis_ — nothing else. CLAUDE.md gains a Formatting section recording the split and why the config settings matter.

Checks

bun run check:ci green — Biome clean, prettier clean, tsc --noEmit clean, 82 tests pass. No source changes.

The `code-walkthrough` skill no longer builds this file with showboat, so
WALKTHROUGH.md is ordinary markdown. Regenerating it surfaced a formatting
gap this repo had been living with invisibly, which is why both changes
land together.

**The document.** 1429 -> 1096 lines, 94 fenced blocks -> 41. The old form
paired every snippet with a captured `output` block, so 39 of its 47
commands were `sed` ranges whose only assertion was that text still matched
a file; captured output ran 1.8x the prose. Snippets are now quoted inline
and labelled `file` -- `symbol` rather than by line range.

Dropping showboat also removed constraints that had been shaping content
rather than formatting. "What the tests cover" shows real `bun test` output
instead of a `grep` of test names, which was a workaround for verify
breaking on non-deterministic output. The architecture table is a table
instead of a shell loop, which was a workaround for verify breaking on
repo-tracking output.

Fidelity is checked rather than assumed: each labelled `ts` block was
diffed against the source file it names, 271 substantive lines, 0
mismatches.

**Prettier.** That check initially failed. The user-level auto-format hook
runs prettier on any markdown it sees, and this repo declared no prettier
config, so it used defaults -- including `embeddedLanguageFormatting:
"auto"`, which rewrote quoted TypeScript to double quotes at width 80
against this repo's Biome style of single quotes at 100. Three snippets
stopped matching their source.

Biome 2.5 does not process markdown at all, so prettier is not a redundant
second formatter here; it is the only one that can do this job. It is now a
declared devDependency wired into `check`, `check:ci` and `format`, scoped
to `**/*.md` so it never fights Biome over TypeScript or JSON. Markdown
drift now fails the pre-push hook like any other formatting -- verified by
pushing bad whitespace through the gate and watching it block.

`.prettierrc.json` sets `embeddedLanguageFormatting: "off"`, which is
load-bearing rather than stylistic. `.prettierignore` excludes `.issues/`:
it is ignored through the global core.excludesfile rather than this repo's
.gitignore, so git hides it and prettier does not.

THEORY.md changes are prettier normalizing `*emphasis*` to `_emphasis_`,
nothing else. CLAUDE.md gains a Formatting section recording the split.

Co-Authored-By: Claude
@philoserf
philoserf merged commit 21ddeaa into main Sep 16, 2026
3 checks passed
@philoserf
philoserf deleted the docs/plain-markdown-walkthrough branch September 16, 2026 13:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant