The starter’s routes and layouts call these helpers, and so will yours when you customize them. This page covers the ones customization needs; each package entry exports more, and its TypeScript types document every export. The package follows semver, and nimbus-docs migrate handles breaking changes (Upgrading).
Page routes
From @cloudflare/nimbus-docs. The starter’s src/pages/[...slug].astro uses them.
| Helper | What it does |
|---|---|
getDocsStaticPaths |
getStaticPaths for a docs collection: one path per page. |
getDocsPage(Astro) |
The page’s entry, rendered Content and headings, or a 404 Response for a request-rendered miss. |
getRouteFlags(entry) |
Whether the page shows the sidebar and the table of contents, after frontmatter and config. |
entryRouteKey(id) |
The URL segment for an entry id, with index collapsed. |
Navigation
| Helper | What it does |
|---|---|
getSidebar(slug, { collection }) |
The sidebar tree for a page, with the current page and its groups marked. |
getSidebarSections(slug, { collection }) |
The site’s top-level sections, for the header’s section tabs. |
getPrevNext(slug, { sidebarTree, overrides }) |
The previous and next pages in sidebar order, after prev and next frontmatter. |
getBreadcrumbs(slug) |
The trail of groups above a page. |
getTOC(headings, config) |
The table of contents for a page, from its headings and tableOfContents settings. |
Page details
| Helper | What it does |
|---|---|
getEditUrl(entry) |
The page’s edit link, from editPattern, or undefined. |
getLastUpdated(entry) |
The page’s last git commit date, or undefined when git can’t say. |
getVersionStatus(key) |
Whether a version is current, deprecated or hidden, for banners. |
getPageLanguage(locale?) |
The page’s language, locale or config.locale, and dir: "rtl" when it’s written right to left: { lang, dir } for <html lang dir>. |
getCollectionLlmsUrl(collection) |
The llms.txt that indexes a collection. |
getPublishedLlmsUrl(collection?) |
The llms.txt a route of the site serves for a collection: its own, else the site’s, else null. |
URLs
| Helper | What it does |
|---|---|
withBase(path, base) |
Adds Astro’s base to a site path, once. |
stripBase(pathname, base) |
Removes it. |
entryRouteKey(id) |
An entry’s route: its id with a final /index removed. |
Route matching uses logical, unbased paths; links sent to a browser use based paths:
import {
entryRouteKey,
stripBase,
withBase,
} from "@cloudflare/nimbus-docs/runtime";
const route = entryRouteKey(entry.id);
const requestedRoute = stripBase(Astro.url.pathname, import.meta.env.BASE_URL);
const href = withBase(`/${route}`, import.meta.env.BASE_URL);Nimbus rejects ambiguous or unsafe generated routes during the build. Common causes include both foo and foo/index, collisions with reserved llms.txt routes, encoded path separators, and encoded . or .. segments. The build error names the conflicting entries.
Page URLs
getDocsPage() and getCollectionPage() return each page’s URLs next to entry, Content, and headings, so page routes don’t build them by hand. getIndexedEntries() returns the same values on each IndexedEntry.
| Field | Example | Description |
|---|---|---|
markdownUrl |
/blog/welcome/index.md |
The page’s clean Markdown version. /index.md for the site root. |
sourceUrl |
/blog/welcome/index.mdx |
The page’s authored source. undefined for entries without an authored body. |
ogImageUrl |
/og/blog/welcome.png |
The page’s generated OG card. /og/index.png for the site root, /og/blog.png for the root of a collection mounted at /blog. |
The URLs follow the entry ID. Astro’s glob loader slugifies file paths, which drops dots: src/content/docs/1.1.1.1/encryption.mdx gets the ID 1111/encryption. Dots are kept where Astro doesn’t slugify: a version prefix (/v1.2/guide/), an API operation (payment.succeeded), or a slug frontmatter field, which Astro uses as the ID. docsCollection() accepts slug without any schema change.
Each URL is site-relative, without Astro’s deployment base; the starter’s layouts add the base when they emit it. The starter’s page route uses the URLs directly:
---
const page = await getDocsPage(Astro);
if (page instanceof Response) return page;
const { entry, Content, headings, markdownUrl, ogImageUrl } = page;
const socialImage = entry.data.socialImage ?? ogImageUrl;
---getOgImagePages() returns one entry per indexed page, keyed by the card’s path under /og/ so the card is written at that page’s ogImageUrl, with the page’s IndexedEntry as the value. getPageSection(page) returns the label of that page’s nearest parent, which the card prints above the title. The starter’s src/pages/og/[...slug].ts passes it through; see Customize OG cards.
API reference pages
From @cloudflare/nimbus-docs/runtime. Add an OpenAPI reference shows them in the API route.
| Helper | What it does |
|---|---|
getApiStaticPaths(collection) |
getStaticPaths for an API reference route, across its versions. |
getApiRoute(Astro) |
The page and sidebar for an API route, or a redirect or 404 Response. |
getApiRoot(Astro, { collection, version }) |
A version’s root page, with its index of every endpoint, from any route. |
getApiNav(Astro, { collection, href }) |
The API sidebar opened at one API page, from any route, and that page’s version. |
getApiVersions(collection) |
The versions of an API, for a picker. |
getVersionSwitchUrl({ collection, sourceVersion, id, targetVersion }) |
The same page in another version, or that version’s landing page. |
getApiVersionHead(collection, version, coordinate, request) |
The canonical link and alternate versions, for a custom API head. |
apiIndexRows(index), chunkApiIndex(index, { size }) |
Flatten a root page’s index, or split it the way the API home does. |
Build a page from the whole reference
To build your own page from the whole reference, read a version’s root page with getApiRoot from @cloudflare/nimbus-docs/runtime; leave out version for the default. Its index holds every operation and webhook exactly once, each with its method, path and link. apiIndexRows(index) flattens it, and chunkApiIndex(index, { size }) splits it the way the home does.
---
import { apiIndexRows, getApiRoot, withBase } from "@cloudflare/nimbus-docs/runtime";
const root = await getApiRoot(Astro, { collection: "api" });
const rows = root ? apiIndexRows(root.index) : [];
---
<ul>
{rows.map(([method, path, label, href]) => (
<li><a href={withBase(href, import.meta.env.BASE_URL)}>{label}</a> <code>{method} {path}</code></li>
))}
</ul>Show the API sidebar on your own pages
A page of your own can show the same sidebar as the API pages. getApiNav returns it opened at the API page href names, with that page and its parents expanded and nothing marked current:
---
import DocsLayout from "@/layouts/DocsLayout.astro";
import { ApiSidebarPanel } from "@/components/ui/api-sidebar";
import { getApiNav } from "@cloudflare/nimbus-docs/runtime";
const result = await getApiNav(Astro, { collection: "api", href: "/api/d1/" });
if (!result) return Astro.redirect("/404");
---
<DocsLayout title="D1 CLI">
<ApiSidebarPanel slot="sidebar" nav={result.nav} version={result.version} />
<!-- the page -->
</DocsLayout>ApiSidebarPanel is the sidebar ApiLayout renders: the filter, which searches the whole API when groups load on demand, groups that load when opened, and open groups and scroll kept across pages. <li> rows you put inside it, such as an overview link, come before the API’s rows.
Write href as the sidebar writes its own links: the API’s mount path and, in query-version mode, its ?version=, without the site base. result.version is the version it resolved to.
It returns null when the collection or page doesn’t exist, or the href redirects. It reads only the sidebar, never the page, so it’s cheap on any route, including with bundle: false.
It throws when the build is broken. With bundle: false, it also throws when the server is at its read limit, with an error named PageAssetReadOverloadError. API pages answer that with a 503 and Retry-After: 1; a page of your own can do the same.
Link to the same page in another version
const href = await getVersionSwitchUrl({
collection: "api",
sourceVersion: "2026-10-09",
id: coordinate,
targetVersion: "2026-10-02",
});Import it from @cloudflare/nimbus-docs/runtime and apply withBase once when rendering the link. Pass the page’s exact source version, including on the latest version’s pages. The link goes to the same operation in the target version, or to that version’s landing page when the operation doesn’t exist there.
For custom API heads, use getApiVersionHead; the starter’s ApiLayout uses it too.
Collections
From @cloudflare/nimbus-docs/content, in src/content.config.ts.
| Helper | What it does |
|---|---|
docsCollection(options) |
A docs collection; schemaFields adds frontmatter fields, and markdownFields writes them into each page’s Markdown version. |
partialsCollection(options) |
The reusable snippets that <Render> includes. |
componentsCollection(options) |
Component pages, like the component catalog. |
apiCollection(options) |
The pages generated from an OpenAPI spec. |
Behaviour in the browser
From @cloudflare/nimbus-docs/client, in component scripts.
| Helper | What it does |
|---|---|
mount(selector, init) |
Runs init for every matching element on each page, including after client-side navigation, and its cleanup when the page goes. See Custom components. |
initTabs(config) |
Tab-list keyboard and selection behaviour. |
makeDisclosure(options) |
Open-and-close behaviour for a disclosure. |
onShortcut(key, handler, { within? }) |
Runs handler when key is pressed anywhere on the page, or only while focus is inside within: a character such as "/", or a combo such as "Mod+K" (⌘ on macOS, Ctrl elsewhere). Returns a function that unbinds it. See Keyboard shortcuts. |
syncShortcutHints(root?) |
Writes each data-nb-shortcut-hint as this platform shows its key, and each data-nb-shortcut-for control’s aria-keyshortcuts; both then follow the reader’s switch. |
shortcutLabel(key), ariaKeyShortcuts(key) |
A key as a reader sees it (⌘K, Ctrl K, [) and as aria-keyshortcuts names it. |
singleKeyShortcutsEnabled(), setSingleKeyShortcutsEnabled(on) |
The reader’s choice to turn single-key shortcuts off. |
Markdown plugins
From @cloudflare/nimbus-docs/markdown, in markdown.hastPlugins in the integration options. See Markdown and MDX.
| Plugin | What it does |
|---|---|
tableScroll() |
Wraps wide tables so they scroll instead of overflowing. |
externalLinks(options) |
Opens links to other sites in a new tab, with an arrow after the text. |
titleFigure(options) |
Turns an image with a title into a figure with a caption. |
math(options) |
Renders math as MathML at build time; turn on features: { math: true } too. |
Type your own plugins with HastPluginDefinition and HastVisitorContext from the same entry.
Components
| Component | What it does |
|---|---|
@cloudflare/nimbus-docs/components/Icon.astro |
Renders an icon by name, such as ph:check. |
@cloudflare/nimbus-docs/components/NimbusHead.astro |
The page’s head: title, description, canonical, share card and agent discovery tags. locale and socialImageAlt set a page’s language and share-image alt. |
@cloudflare/nimbus-docs/components/NestedContent.astro |
Shows another page’s content inside this one, such as a release on a changelog list: its h1 and h2 become headingLevel and drop their ids, and links to its sections go to sourceUrl. |