---
title: "Package API"
description: "The helpers your pages, layouts and components call from @cloudflare/nimbus-docs, grouped by task."
---

> Documentation Index
> Fetch the complete documentation index at: https://nimbus-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Package API

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](/publish/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. |
| `getCollectionLlmsUrl(collection)` | The `llms.txt` that indexes a collection. |

## 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:

```ts
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:

```astro title="src/pages/[...slug].astro (excerpt)"
---
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](/ai/override-markdown#customize-og-cards).

## API reference pages

From `@cloudflare/nimbus-docs/runtime`. [Add an OpenAPI reference](/api-reference/openapi/setup) 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. |
| `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.

```astro title="src/pages/endpoints.astro"
---
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>
```

### Link to the same page in another version

```ts
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](/ai/publish-markdown#add-your-own-frontmatter). |
| `partialsCollection(options)` | The reusable snippets that `<Render>` includes. |
| `componentsCollection(options)` | Component pages, like the [component catalog](/components). |
| `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](/styling/custom-components). |
| `initTabs(config)` | Tab-list keyboard and selection behaviour. |
| `makeDisclosure(options)` | Open-and-close behaviour for a disclosure. |

## Markdown plugins

From `@cloudflare/nimbus-docs/markdown`, in `markdown.hastPlugins` in the integration options. See [Markdown and MDX](/writing/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. |

## 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. |
| `@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`. |

Source: https://nimbus-docs.com/styling/package-api/index.mdx