Publish the examples as markdown, and link it from each page

[abernier]

Why

The catalog was JSON, and the document an agent actually reads was assembled from it inside the docs MCP server (pmndrs/docs#562). That put the rendering behind one consumer.

An agent handed an example's URL — pasted into a chat, arrived at from a search, run by a vendor with no pmndrs plugin — gets HTML and has no route to the same text. And this site is output: "export", so it cannot render one on demand.

So the rendering moves here, where it can be published.

What

bin/lib/render.mjs emits, next to the JSON:

• /catalog/index.md — the whole gallery, one line per demo
• /catalog/<name>.md — one demo in full: facts, asset attribution, then each source file fenced

and every example page points at its own, the way this generator's sites already point at llms.txt:

<link rel="alternate" type="text/markdown" href="https://pmndrs.github.io/examples/catalog/caustics.md" />

The gallery index is linked site-wide from the layout — as a literal <link> rather than page metadata, since a page's own alternates replaces the layout's field rather than merging with it.

The MCP server now passes these on verbatim (pmndrs/docs#563): ~470 fewer lines there, and one rendering instead of two that could drift apart.

The JSON stays

It is the structured form — dependencies as a map, sizes as numbers — and it is the step the markdown is built from. Nothing consumes it today, which is also why it carries no $schema: a schema for an artifact with no reader is maintenance for a reader that may never come. Worth adding the day something parses it, when its needs are known.

Notes

• catalog_url joins website_url/embed_url in lib/helper.ts, so URL derivation stays in one place; catalogIndexUrl is exported for the layout, which has no per-example port to resolve
• bin/lib/** added to website#build3 inputs, with a test/turbo-cache.test.ts case pinning it — a cache hit that skipped the renderers would serve documents describing examples that have since changed
• test/render.test.ts covers what the docs repo used to: the size marker, the title elision, fences long enough to survive backticks inside a file, and attribution

Verification

• pnpm exec vitest run — 34 passing (17 render, 17 turbo cache)
• pnpm lint, pnpm format:check
• built with BASE_PATH/BASE_URL set: 336 files in out/catalog/, and both <link rel="alternate"> render with absolute URLs on an example page, the index alone on the home page
• served that output and ran the real MCP route against it with EXAMPLES_URL — examples://index returns 167 lines, get_example("spotlight-shadows") returns the published document including its attribution, a traversal name is refused

🤖 Generated with Claude Code