Guides, brand and several APIs, beside the reference.
A reference alone is not documentation. Guides sit beside the operations and link into them, the whole thing wears your brand without a build step, and one installation can carry every API you publish.
One portal page, cut down the middle — thirty-five bundled themes, or a block of CSS variables of your own.
Your Markdown, in the navigation.
Declare a Markdown file in one line and it becomes a page in the navigation — array order is nav order, groups nest one level, and external links sit alongside. Point at a file you already have: a README, a CHANGELOG, an existing guide. It is fetched like the schema, when it is read. Nothing to build, nothing to redeploy beyond your own files.
Pages talk to the reference rather than describing it from a distance. An apidoc: link renders inline with a method badge; an apidoc:operation fence renders a full operation card. Callouts, language-synced code tabs, a table of contents and prev/next come with the format, and prose is indexed into the ⌘K search. <Cards>, <Steps> and <Tabs> give you the components people bring MDX in for, written the same way — and nothing is compiled: a renderer that does not know them still shows the prose.
A guide can even read personally: {{var}} in prose resolves from the reader’s own environment, with sensitive values masked rather than printed. That is the personalized documentation of a hosted platform, with no server and no account behind it.
{
"docsPages": [
{ "title": "Getting started", "url": "./guides/start.md" },
{ "title": "Architecture", "url": "./guides/architecture.md" }
]
}
Your brand, without a build.
Thirty-five daisyUI themes ship in the bundle, plus the authored apiglow / apiglow-dark pair that is what a fresh install looks like. Your own theme is a block of CSS custom properties declared on the host page — no Tailwind config, no rebuild, no fork.
Because the themes are yours to author, the contrast is yours to get right: the product gates its own authored pair on WCAG contrast, and a custom theme is checked the same way it would be anywhere else — by you.
Several APIs, one installation.
A single install can carry several OpenAPI documents. Each keeps its own environments, its own history and its own search scope, with no leakage between them — a reader switching from the Billing API to the Shipping API does not inherit the first one’s credentials.
Per-spec overrides let one document differ from the others where it needs to, and the navigation can send support and legal pages below the reference as an appendix rather than a second docs section.
The reading experience, unglamorously.
⌘K search with a scope filter that says where a result lives — reference, guides or scenarios — answering in under 200 ms on a 12 MB, 1220-operation document, a budget the app enforces in its own CI. A fully localized interface, where adding a language is one JSON file and only the active one is downloaded. WCAG 2.2 AA targeted on every interactive path: navigation, try-it, search.
A whole portal built this way — reference, bilingual guides, chained scenarios and a sandbox that answers in the page — is at the Northwind Rail showcase. Northwind Rail is fictional; the portal is not.
What it is not.
Prose pages are Markdown, not MDX: there is no place to drop a component of your own. Operation cards are links into the reference rather than embedded consoles, and groups nest one level deep.
A theme is CSS custom properties. If your brand needs a different layout rather than a different palette, this is not the lever.