Markdown alternates
Append index.md to any page URL and you get that page as Markdown: /docs/email/held-drafts/ becomes /docs/email/held-drafts/index.md. The HTML stays canonical; the Markdown is an alternate representation generated from the same page registry in the same build, so the two cannot disagree. It carries no navigation, no menus and no scripts.
The URL rule#
There is one rule and no exceptions: the Markdown twin of a page is its URL with index.md appended. Hubs, changelog and ordinary pages all follow it. You never have to derive a slug or look up a mapping.
HTML https://connectbyjbrh.com/developers/markdown-mirrors/
Markdown https://connectbyjbrh.com/developers/markdown-mirrors/index.mdYou do not have to construct it yourself either. Every record in /docs-manifest.json carries a markdown field holding the absolute URL, and every entry in /llms-full.txt prints it beside the canonical link. A client that reads either of those never builds the string by hand, which matters the day a URL contains something you did not anticipate.
What the body is, and what it is not#
The Markdown is generated from the same page registry as the HTML by tools/docs_build.py, in the same run. That is the point of it: it is not a scrape of the rendered page and not a hand-maintained copy, so it cannot drift, and there is no second wording of a fact to go stale.
What it leaves out is the chrome — navigation, breadcrumbs, search box, footer links. For a model, that is the difference between a document and a document wrapped in a site. public_docs.fetch says as much in its own docstring: the Markdown mirror is the right body to hand an agent because it carries no navigation for a model to mistake for content.
| Route | Returns | Cap |
|---|---|---|
GET <url>index.md | The file itself, as text | None — the whole file |
GET /api/public/docs/page?ref=<url> | The record plus body and body_format: "markdown" | 60,000 characters |
MCP fetch_public_doc | The same record, through the same function | 60,000 characters |
Which one is canonical#
The HTML is. The Markdown is an alternate representation of the same resource, published for machine consumption; it is not a separate page and it is not a competing URL for indexing purposes. If you are quoting a Connect page anywhere a human might follow the link, cite the HTML URL and read the Markdown.
The server helps keep that boundary tidy in one small way. public_docs.canonical_redirect sends /docs/phone to /docs/phone/ so that a missing trailing slash is one page rather than two — and it deliberately leaves anything with a file extension alone, which is why index.md is served rather than redirected into the HTML.
Why the search index reads the Markdown too#
The corpus search index tokenises each page's title, description and summary at full weight, and then the first 12,000 characters of its Markdown body at weight zero. The effect is that a page can be *found* by a phrase that appears only in its prose without that phrase outranking a page whose title is about it.
The comment in the code names the case that forced the design: without body indexing, a search for "call recording" finds nothing at all, because no page is titled after a capability that is not available — which is precisely the question a person asks. Zero-weight body terms make the honest page findable without letting a passing mention win the ranking.
For your own index, the same split is worth copying: embed summary for retrieval, keep the Markdown body for the answer, and store status beside both so that what you generate can say *foundation* when the page does.
Questions#
Is the Markdown byte-identical to what the HTML shows?
It is the same content from the same source, rendered for a different medium. Tables, lists, procedures and code blocks all survive; the navigation and the page furniture do not. No fact appears in one and not the other.
Can I crawl only the Markdown?
You can, and the manifest makes it easy — every record carries the Markdown URL. Fetch politely and cache on updated; the files change on a deploy, not on a request.
Why 60,000 characters on the API body?
It bounds a single response so one very long page cannot become an unbounded read for a caller that only wanted a document. Fetching index.md directly has no such cap, so nothing is unreachable — it is a limit on one route, not on the corpus.