API — Machine-readable content routes

• Status: Current
• Last updated: 2026-11-01
• Related ADRs: ADR-0013, ADR-0015, ADR-0011

Snapshot of the system as it stands today. Edit in place; never record what changed.

All of these are prerendered at build time (they read no request data, ADR-0016), need no authentication, and return every page in content/. None filters anything out. Pages live at the root, /<slug>/… (ADR-0015). src/proxy.ts handles line redirects and Markdown on paths whose first segment is a catalogued slug, and answers any path that is not a page with a 404 (ADR-0034).

EndpointsCopy Anchor Link

---

GET /llms.mdx/<slug>/content.mdCopy Anchor Link

Purpose. The processed Markdown of one page, headed # <title> (<url>). A page in a package's version line follows the heading with > Documents <package> <version> (<line name>, <latest | in development | older version>)., such as > Documents lodestar 0.1.4 (v0.1, latest).

Authorisation. Public. Nothing keeps private content out — see AGENTS.md §6.1.

Responses

Notes. /<page>.md, and /<page> when the request prefers Markdown, are rewritten here by src/proxy.ts; the second adds Vary: Accept.

---

GET /llms.txt and GET /llms-full.txtCopy Anchor Link

Purpose. llms.txt lists every page; llms-full.txt returns all of their Markdown in one response. Both come from docsLlms in src/lib/source.ts. In llms.txt, each version line is named with its line name, version and channel, such as v4.0 — 4.0.1, latest or dev — 5.0.0-dev, in development.

Authorisation. Public.

Responses

---

GET /og/<slug>/image.pngCopy Anchor Link

Purpose. A page's share image, showing its entry, track, line, title, description and the site's name. ./crawler-routes.mdx has the details and the home page's image.

Authorisation. Public.

Responses

---

GET /static.jsonCopy Anchor Link

Purpose. Every page as an Algolia DocumentRecord, from toDocuments(source). The build reads this route's output and pushes it to the index (scripts/sync-content.ts).

Fields added here (ADR-0013 decision 8). tag is the page's scope, the index's one facet: <package>, <package>:maintain, <package>:use or <package>:use:<segment> for catalogue pages (ledgerly:use:3.x-lts, docs:maintain), and site for anything outside an entry. The home page's search filters on it. Catalogue pages also carry extra_data with package, kind, ecosystem, track, line (the line's name) and channel; these reach the index, but the current index settings neither retrieve nor rank on them. Ranking latest and Maintain pages first needs an index settings change, which is publishing and waits for the owner.

Authorisation. Public — it is served by the deployed site as well as read by the build.

Responses

GET /diagrams/<project-slug>/<slug>.htmlCopy Anchor Link

One Archify diagram: the file at diagrams/<project-slug>/<slug>.html, exactly as Archify's deliver wrote it, with the site shell added (src/lib/diagram-shell.ts, ADR-0022). Prerendered by src/app/diagrams/[project]/[file]/route.ts for every file listed at build; no other path is served and no request data is read. <Diagram> frames it with ?frame=1&theme=…; Open full screen links to it with ?theme=… only. The frame carries allow="fullscreen".

Query. Read by the shell's script in the browser, never by the server: frame=1 hides Archify's title, subtitle, notes rail, theme and style buttons and credit, and reports the content height to the embedding page with postMessage({ type: 'archify-height', height }), including an open toolbar menu. Present takes the frame to fullscreen; where fullscreen is refused, the frame posts { type: 'archify-present' } and the page opens <src>?theme=…&present=1 itself. theme=light|dark sets the theme before first paint and present=1 opens Archify's Present stage (both Archify's own parameters).

Headers. Content-Security-Policy: sandbox allow-scripts allow-downloads, set for /diagrams/:path* in next.config.mjs, so a direct visit runs the diagram's script in an opaque origin, as the embedding frame does (sandbox="allow-scripts allow-downloads", no allow-same-origin).

Authorisation. Public. Everything in diagrams/ is published; no diagram of a private project goes there.

Not indexed. The files are not in static.json, the search index or llms.txt. A page's Markdown carries the diagram's Mermaid fence, never the <Diagram> tag or the file's URL.

Build checks (src/lib/remark-diagrams.ts as each page compiles; src/lib/diagrams.ts, run by the loader plugin in src/lib/diagrams-plugin.ts; and <Diagram> itself): a Mermaid fence outside a <Diagram> (templates excepted), a <Diagram> without a plain src and title or without exactly one Mermaid fence, a src that is not /diagrams/<project-slug>/<slug>.html or has no file, an HTML without its JSON (or the reverse), an HTML no page uses, any file in public/diagrams/, and an Archify receipt (*.delivery*.json) in diagrams/ or public/ each fail the build.

Responses