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

docs/README.md: generate its list of pages from the pages' front matter (child of #14248) #14382

Merged opened this

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

Merged

docs/README.md now builds its list of pages from the pages' own front matter, the way the features index does. I did not run the whole suite.

Notes

shipped production is serving it deploy 6521495

opened this

docs/README.md now builds its list of pages from the pages' own front matter, the way the features index does. I did not run the whole suite. fast.ts named 2,309 test files, so I ran 88 tests in 18 files covering docs, the guide, feature front matter, the features index script and the README cap; one failed and I fixed it. tsc and gate.ts --fix came back clean. I re-ran only test/docs-index.test.ts and test/guide.test.ts (16 pass) after the last edit.

What changed

  • Front matter: each page declares its rows with docs: <heading> | <link words> | <sentence>, plus an optional | #anchor. All 25 hand-typed rows moved into the front matter of the pages they link, so the list reads the same as before except for ordering.
  • README: the body is now one <!-- pages --> line under each heading. A short note near the top says how to add a page.
  • Where it runs: src/view/docs_index.ts builds the rows, and src/view/docs.ts applies it when README.md is read. It scans docs/.md, docs/designs/.md and docs/features/*.md.
  • Tests: test/docs-index.test.ts covers the parser, the sorted rendering under each topic, and a head with no typed row. It also checks that every page that asks for a row shows up in the README as served.

What I chose not to do

  • Ordering: rows are sorted by link words rather than keeping the old hand order, so a page needs no ordering key.
  • Operations log row: it stays typed in the head, because it links a .log file and not a page.
  • Guide paragraph: the "Start here" paragraph stays as it was, since its order is the guide's own.
  • Pages with no row: top-level pages that were never in the README, such as FEED.md, gained nothing. The test refuses a page whose row is missing, not a page with no row at all.

Try it: open /docs for the rendered list. To add a page, put docs: Develop it | My page | what it says. at the top of the file.

Closes #14353

commented

docs/README.md now builds its list of pages from the pages' own front matter, the way the features index does. I did not run the whole suite. fast.ts named 2,309 test files, so I ran 88 tests in 18 files covering docs, the guide, feature front matter, the features index script and the README cap; one failed and I fixed it. tsc and gate.ts --fix came back clean. I re-ran only test/docs-index.test.ts and test/guide.test.ts (16 pass) after the last edit.

What changed

  • Front matter: each page declares its rows with docs: <heading> | <link words> | <sentence>, plus an optional | #anchor. All 25 hand-typed rows moved into the front matter of the pages they link, so the list reads the same as before except for ordering.
  • README: the body is now one <!-- pages --> line under each heading. A short note near the top says how to add a page.
  • Where it runs: src/view/docs_index.ts builds the rows, and src/view/docs.ts applies it when README.md is read. It scans docs/.md, docs/designs/.md and docs/features/*.md.
  • Tests: test/docs-index.test.ts covers the parser, the sorted rendering under each topic, and a head with no typed row. It also checks that every page that asks for a row shows up in the README as served.

What I chose not to do

  • Ordering: rows are sorted by link words rather than keeping the old hand order, so a page needs no ordering key.
  • Operations log row: it stays typed in the head, because it links a .log file and not a page.
  • Guide paragraph: the "Start here" paragraph stays as it was, since its order is the guide's own.
  • Pages with no row: top-level pages that were never in the README, such as FEED.md, gained nothing. The test refuses a page whose row is missing, not a page with no row at all.

Try it: open /docs for the rendered list. To add a page, put docs: Develop it | My page | what it says. at the top of the file.

Approved

Approved. The preview serves /docs/README.md with every topic filled from the front matter (Use it, Operate it and the rest), no <!-- pages --> marker is left, and the page is plain server-rendered HTML that works with JavaScript off. A malformed docs: line is skipped, the anchor is validated, and file names are matched against a strict pattern. The tests would fail without the change. Both doors share docText, so the terminal sees the same list. Nothing was added to the root README.

Two things I would do next:

  1. readDoc for README.md now scans three directories and reads about 30 files on every request. Cache the result by directory mtime, or build it once at boot, so the page stays in milliseconds (docs.ts:58).
  2. The test excludes the bottleneck row with a string special case (docs-index.test.ts). Give the operations-log row a docs: home, or a named constant, so the test needs no exception.
Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs