Skip to content
Nimbus

Changelog

Every release of the nimbus-docs package and the create-nimbus-docs scaffolder.

2026

nimbus-docs 0.19.0

Minor Changes

  • #265 2440889 Thanks @MohamedH1998! - - agents: { discovery: false } leaves origin-root agent discovery to the site that owns the domain: no /.well-known/ard.json, ai-catalog.json or api-catalog, no rel="ard" or rel="api-catalog" homepage links, and your own .well-known files are kept.

  • #283 ed581a0 Thanks @MohamedH1998! - - An API reference can be the whole site: a route at src/pages/[...slug].astro serves the API collection at the root. Every URL Nimbus builds for it is root-relative: pages, the version picker, the sidebar, breadcrumbs, Markdown versions, llms.txt, the sitemap, openapi.json and the API catalog.

    • A site whose content.config.ts declares no docs collection no longer queries one for the sidebar, so Astro’s “collection does not exist” warning is gone. A sidebar that names docs still queries it.

  • #273 352a245 Thanks @MohamedH1998! - A redesigned API reference:

    • The API home lists every endpoint, grouped by x-tagGroups, with a filter; large specs load in parts as you scroll. The API route serves the later parts at /api/index/2/ and on, noindex and left out of the sitemap and search; it takes the part size as homeChunkSize in both getApiStaticPaths and getApiRoute (without it, the home is one page), and getApiRoute returns the parts as home.
    • Section pages list their endpoints name first, with the method and path beneath.
    • The API version picker sits in the header, at every width.
    • Code rail lines sit on whole pixels, with quieter line numbers; section titles are in full ink.
    • The API sidebar’s rows match the docs sidebar’s.
    • Section page operations gain method, path, description and deprecated, and the root page gains an index of every endpoint.
    • getApiRoot reads an API version’s root page from any route; chunkApiIndex and apiIndexRows split and flatten its index.

    nimbus-docs migrate lists the optional steps to adopt it.

  • #274 961e85d Thanks @MohamedH1998! - - New sites’ share cards show the site’s logo, the page’s section and its title, on white. A long title shrinks before it’s cut and stays within three lines.

    • The card’s look lives in the site’s src/pages/og/_card.ts; the logo is drawn once, in src/components/logo.ts, for the header and the cards.
    • @cloudflare/nimbus-docs/og fits text by measuring it and renders cards to PNG. It needs satori and @resvg/resvg-js, optional peers.
    • getPageSection(page) returns the label of a page’s nearest parent, from the sidebar for docs pages and from the spec for API pages.

  • #274 91eb2e9 Thanks @MohamedH1998! - - Card takes href: the whole card becomes the link.

    • Diagram buttons and controls keep their 32px height inside prose.
    • PUT and PATCH method chips meet 4.5:1 contrast in light mode.
    • The version picker and the API field toggle are named by their visible text.

  • #288 aafc259 Thanks @MohamedH1998! - - docsCollection({ markdownFields }) writes the named frontmatter fields into each page’s .md and .mdx.

    • NestedContent shows another page’s content inside this one, its headings below yours and its section links pointing back to its page.
    • nimbus-docs add changelog builds release notes: 10 releases a page, a page per release, and an @astrojs/rss feed. Existing changelogs keep working (review entry changelog-release-notes).

  • #267 eb1a3a6 Thanks @MohamedH1998! - - A collection is served where its route file is: src/pages/products/sdk/[...slug].astro serves sdk at /products/sdk, and every URL Nimbus builds follows: pages, sidebar, Markdown versions, llms.txt, sitemap, search, social cards, and for an API its versions, openapi.json and catalog entry. Sites whose route folders match their collection names build the same output.

    • getCollectionUrl(collection) returns where a collection is served, for links in components. A name that isn’t a page collection throws.
    • nimbus-docs check lists where each collection is served when a route moves one; check --json always includes it.
    • Sites that build broken URLs today now fail with an error naming the file and the fix: several routes for one collection with none at its default URL, two collections on one URL, a collection served only from dynamic folders, a docs or version route away from its URL, a page under another collection’s moved URL, a route helper in a route whose parameter isn’t slug ([...path].astro), or a route helper running in a route its collection isn’t served from.
    • A sidebar prefix for a collection served by a route helper is deprecated: the route sets the URL.
    • getIndexedTopLevel() groups a moved collection under its URL: a group’s slug and label can contain / (products/sdk). Components that build /${slug}/llms.txt or show label should expect it.
    • Two new warnings, from the build and check: a second static route for a collection that’s already served elsewhere (its pages duplicate the collection’s), and a helper route in a nested folder whose getStaticPaths Nimbus can’t read.
    • nimbus-docs lint follows the pages Astro writes for a dynamic redirect ("/sdk/[...slug]": "/products/sdk/[...slug]") instead of taking them for pages, so a redirect to a missing page is reported and nimbus/redirected-link finds links through it.
    • nimbus-docs lint suggests the new URL for a link into a moved collection (/sdk/setup → /products/kit/setup), and never suggests the site root or an error page as a near-match. Builds record each collection’s URL in .nimbus/routes.json for this.
    • nimbus-docs check checks collections added since the last build, alongside the ones that build recorded.

  • #268 4b77047 Thanks @MohamedH1998! - - Request-rendered collections are served where their route file is too, nested folders, kept copies and base included. A request-rendered route under a static folder no collection is served from returns not found and logs why; one under a dynamic folder ([locale]/sdk/) isn’t checked, since its folder depends on the URL. A request-rendered collection’s index page is listed in the sitemap, search and route checks at the collection’s URL (/products/kit/), not /products/kit/index/.

    • In astro dev, moving, adding or removing a collection’s route file restarts the server onto the new URLs and logs the redirect to add. Editing a route’s template doesn’t restart.
    • With the nested [...section]/llms.txt route, a collection at a nested URL is linked from the llms.txt of the section above it, not only from the root llms.txt.

  • #253 3fa357f Thanks @MohamedH1998! - - A page collection’s files can live anywhere: a glob over a folder outside src/ gets callouts, components, citations, links, collision checks and lint like a page under src/content.

    • A loader with no files gets citations, links, Markdown versions, llms.txt and URL collision checks through withNimbusMarkdown().
    • Two files with one slug fail the build in any collection, .md files included; in collections made with the factories, so does a byte-identical copy.
    • sources in the Nimbus config checks out another git repository at build time; docsCollection({ source, base }) and api[].spec: { source, path } read it.
    • A pinned commit is fetched once and builds offline; a branch builds from its last snapshot when the remote is down.
    • NIMBUS_BUILD_ONLY fetches only the sources its collections and api entries read; astro dev, astro sync and astro preview start without a source they can’t fetch, leaving its collections empty, while astro build fails naming what reads it.
    • A repo with a token or password in it is refused; credentials come from git.
    • Pages from a source get the source’s editPattern and no git date.
    • A source page with no frontmatter title takes its first heading, else its file name; the sidebar never shows a blank label.
    • Relative links between a source collection’s pages (2-options.md#signal) become page URLs; a link to a file the collection doesn’t publish stays as written, with a warning.
    • A ref that starts with refs/ (such as refs/pull/12/head) is used as written.
    • nimbus-docs check reports nimbus/source-floating-ref and nimbus/source-unreferenced.
    • nimbus-docs lint reads source snapshots and reports problems by source and repository path; --fix never writes them.
    • nimbus-docs lint says how many Markdown (.md) pages it leaves out.
    • nimbus-docs add source <name|url> adds a content source: git (github, gitlab, bitbucket), notion, or a guide for any provider from its docs URL.
    • add source notion has your agent write a Notion loader into the site, with drafts, slugs and ordering from the database’s properties. It warns when no row publishes, naming the status values the database uses.
    • list --type source lists the sources.
    • Each source guide carries its own route, rendering and sidebar steps, ends with what to report to the user, and prints from its first heading.

  • #270 0b30e24 Thanks @MohamedH1998! - - A collection served inside an autogenerated sidebar folder appears in that folder, as a group linking its landing page, so breadcrumbs and previous and next links cross between them. Its index page sets the group’s label and order, shows only its landing (hideChildren) or leaves it out (sidebar.hidden); naming it in sidebar.items, or linking to its URL there, places it by hand; a labeled { autogenerate: { collection } } group for one links its landing page and holds the collections inside it. A page the sidebar leaves out keeps the breadcrumbs of the folders above it, and a crumb, titled like the page, for each page between there and itself. A docs folder whose only page is its index becomes a group to hold such a collection, keeping the page’s label. Sites without such a collection build the same sidebar.

  • #284 f256109 Thanks @MohamedH1998! - - outdated and diff compare a site scaffolded with an API reference against the starter it came from: the API route and config read as the starter’s, and the spec as your own.

  • #244 17bf1ce Thanks @MohamedH1998! - - NIMBUS_BUILD_ONLY=docs-es builds one collection, or a comma-separated set, and leaves the others empty; dev, sync and check ignore it with one notice.

    • A slice without the docs collection writes its sitemap, search bundle, stylesheet, assets and llms-full.txt under its prefix, and drops the root files the root slice serves.
    • The root slice’s llms.txt lists every collection’s llms.txt, and search merges the other slices’ indexes at runtime.
    • nimbus-docs lint checks links into other slices against the previous build’s routes, as warnings.
    • A slice build fails on an unknown collection, and on docs version collections split across slices. Slices work under Astro’s base: every URL a slice serves and advertises is under it.
    • The route list nimbus-docs lint checks against reads _redirects where the Cloudflare adapter moves it when the site has a base, so redirects stay known to link checking.
    • searchIndex in virtual:nimbus/config names the search bundles as served URLs, base included. The starter’s search provider loads its slice’s bundle and merges the others.
    • A guide, “Build one locale or one part”, with the Worker and zone routes per slice and a workflow that builds the slice a pull request touched.

  • #272 9a65f9f Thanks @MohamedH1998! - New sites start on the redesigned starter:

    • A fill-in Introduction as the home page, a Writing pages guide and a Components page replace the sample pages and the landing page.
    • A new type scale, steel accent, code blocks, sidebar and header logo.
    • One pagination bar for the previous and next pages; with focus in the bar, [ and ] move between them.
    • Every component part has a data-slot to style it by, except sidebar rows, which stay bare so large sidebars stay light.
    • Components wrap long words, URLs and labels instead of overflowing on phones.
    • Text meets 4.5:1 contrast in light mode, Steps are a real list, manual Tabs render one tab list and pair each tab with its panel.
    • Pages mirror correctly in right-to-left languages; code stays left to right.
    • On phones, sites with several sections show them as tabs under the header.
    • Thin, theme-coloured scrollbars.
    • PageActions renders extra actions passed as children; the layout passes the Copy MCP URL action that way.

    Existing sites keep their look. nimbus-docs migrate lists optional steps to adopt it, the lighter sidebar rows, and the new favicons and asset caching. The registry adds a variants lib that Badge and Button install with them.

  • #243 5604125 Thanks @MohamedH1998! - - agents: { mcp: true } serves a remote MCP server at /mcp with list_pages and get_page over the published Markdown, plus a Server Card at /mcp/server-card, a line in llms.txt and an entry in the AI catalog. It needs a server adapter and @modelcontextprotocol/server; nimbus-docs check reports a missing SDK.

    • Docs pages in the starter show a “Copy MCP URL” page action that copies the server URL when the server is on. On an existing site, run nimbus-docs diff src/components/ConnectMcp.astro --apply and nimbus-docs diff src/components/connect-mcp.client.ts --apply, then pass {capabilities.mcpUrl && <ConnectMcp />} to <PageActions> in src/layouts/DocsLayout.astro, as the Remote MCP server guide shows.

  • #278 b6d4837 Thanks @MohamedH1998! - - Route files say how they render. nimbus-docs check reports each route Nimbus manages whose file disagrees with rendering, and check --fix rewrites it: the prerender line, getStaticPaths on built routes only, and the collection name in a collection route’s page helper. Without rendering, Nimbus builds every one of these routes ahead of time, a collection route such as src/pages/sdk/[...slug].astro included. rendering still wins at build, which now warns once and lists the files.

    • A built dynamic route with no getStaticPaths fails the build, naming the file; Astro can’t build it.
    • The page helpers take the collection as a second argument, such as getCollectionPage(Astro, "sdk") or getApiRoute(Astro, "api", { homeChunkSize }), so a request-rendered route needs no getStaticPaths to say which collection it serves. A route whose getStaticPaths and helper name different collections fails with nimbus/collection-route-mismatch.
    • add adapter-* updates route files after setting rendering, and its recipes run check --fix.
    • outdated and diff compare starter route files in the site’s own mode, so a route check --fix edited doesn’t read as a local change.
    • The starter’s Markdown, llms.txt and docs page routes drop export const prerender = true; the site’s output and rendering decide how they render. A scaffold with a server adapter writes its route files in the mode its rendering gives them.

  • #277 6c4a633 Thanks @MohamedH1998! - - Previous and next links never point a page at itself, when the sidebar reaches a page twice: a group landing that is also a child link, a page linked from two groups, or an anchor link after its page.

    • An isolated sidebar (isolate.boundaries) starts with the group’s landing page instead of dropping it, labeled “Overview” under indexDisplay: "overview-leaf" unless the page sets its own sidebar.label. The landing page gains previous and next links.
    • A labeled { autogenerate: { collection } } group starts with the collection’s landing page at any depth. A collection served one segment deep, such as /sdk, now gets the landing row (“Overview”), previous and next links, and a linked breadcrumb; set sidebar.group.hideIndex: true on its index page to leave it out.
    • On request rendering, /index, /<collection>/index and /<version>/index return 404 instead of a copy of the landing page, as built pages do.
    • nimbus-docs check stops listing and checking a collection deleted since the last build, and notes once that the last build’s collection list is out of date.
    • API descriptions keep text the HTML sanitizer doesn’t know as a tag, such as metadata.<key>, as text instead of dropping it. <script> is still removed, and other unknown tags render as inert text.
    • Code samples for an apiKey in a cookie send it as a cookie, such as curl’s --cookie 'session=<session>', instead of as a header.

  • #260 0c31e84 Thanks @MohamedH1998! - - add --overwrite without a terminal keeps components you’ve edited and exits 1; --overwrite --yes replaces them and says how many carried edits.

    • add a b installs both; an unknown slug stops before anything is installed.
    • check says an optional upgrade stays listed until migrate records the version as reviewed.
    • New pnpm sites build pages with local images: sharp is a starter dependency.
    • astro build --root <site> from another folder finds the social-card font.

Patch Changes

  • #266 662c1c8 Thanks @MohamedH1998! - - add adapter-cloudflare in a coding agent session wires the adapter as it does from a shell; the agent gets the recipe only where the CLI can’t edit the config safely.

    • check reports a missing @scalar/openapi-parser for sites with API collections, and check --fix --yes installs it.
    • Without a terminal, check suggests --fix --yes or editing by hand, whichever --fix can do; migrate --print on a preview build says reviews start on a release.

  • #273 87f4536 Thanks @MohamedH1998! - - The API sidebar lists webhooks in a Webhooks group at the end.

    • A webhook page no longer shows the API’s own top-level security as the receiver’s auth.

  • #288 aafc259 Thanks @MohamedH1998! - - In dev on a Cloudflare site that prerenders with Node, a page’s Markdown version follows edits to the page and to content.config.ts instead of failing until a restart.

  • #284 f256109 Thanks @MohamedH1998! - - astro dev no longer warns that the docs collection doesn’t exist on a site without one.

  • #287 8a43a6c Thanks @MohamedH1998! - Error messages link to the docs pages’ new addresses on nimbus-docs.com.

  • #263 46ecb84 Thanks @MohamedH1998! - - nimbus/image-ref checks image paths under Astro’s base: an inline image needs the base written and a reference definition must not repeat it. lint --fix repairs both when the file is in public/. Its ignore patterns are written without the base, as for links.

    • Under a base, nimbus-docs lint now reports inline images written without it, such as /arch.png, which can fail CI where it passed before. Those images return 404 on the deployed site.

  • #271 f491c71 Thanks @mvvmm! - - astro dev renders a page’s headings when the page is first requested, not every page at content sync. Startup and each file save no longer scale with the number of docs.

    • Builds are unchanged.

  • #264 68b9f7c Thanks @MohamedH1998! - - The API catalog and ard.json list every visible API version: a query-addressed version at its query URL, and the non-default versions of a bundle: false collection, whose specs are now published too.

    • Homepage Link headers advertise only API family defaults and link to the complete catalog, keeping response headers independent of version count.
    • AgentApiPublication.markdownUrl is now optional, because versions without a Markdown reference have none. Code that reads it from @cloudflare/nimbus-docs/types or virtual:nimbus/agent-capabilities must handle undefined.

  • #252 a7ea698 Thanks @sansynx! - nimbus-docs check now reports a missing server adapter for agents.mcp, request rendering and api with bundle: false, and a missing MCP SDK, before a build. Adapter errors name every supported host instead of suggesting Cloudflare first. The placeholder site warning names Cloudflare Workers only when no other adapter is configured, so a Node site with a leftover wrangler.jsonc no longer gets it. The MCP server keeps serving requests on a connection after it rejects an oversized body. Preview builds report starter freshness and diffs correctly, add adapter-* keeps the adapter’s version range, and agents: { MCP: true } suggests mcp.

  • #282 e983040 Thanks @MohamedH1998! - - The package READMEs describe Nimbus as the authoring tool for docs, with the CLI by task and the scaffolder’s options.

  • #285 d45764d Thanks @MohamedH1998! - - migrate’s redesigned-starter step lists src/components/logo.ts, which the new Logo.astro imports.

    • Search results for API pages keep an operation’s name, method and path apart, and no longer index the API home filter’s Retry button.

  • #287 8758eeb Thanks @MohamedH1998! - - lint and check accept relative links between a content source’s pages, which the build turns into page URLs.

    • Search in a slice of several collections skips the other collections’ bundles instead of failing. @cloudflare/nimbus-docs/client exports mergeSearchIndexes, which the starter’s search provider uses.
    • API operation pages keep field names, types and labels apart in search, and leave the expand controls out.
    • The search button’s accessible name starts with its visible label, and API pages name their sidebars.

  • #287 8758eeb Thanks @MohamedH1998! - - add adapter-cloudflare on a pnpm site declines workerd’s build script first, so the install no longer fails.

    • A slice’s Markdown images are published under its prefix, and Markdown images load in astro dev.
    • WebMCP search covers every slice, like the search dialog. On an existing site, pass searchIndex to it as the starter’s WebMCP.astro does.
    • Search excerpts for request-rendered pages read as text, not Markdown syntax.
    • add --overwrite names the files that carry your edits.

  • #272 ba39e21 Thanks @MohamedH1998! - - Relative images now load in a page’s Markdown version and in llms-full.txt.

    • check and lint no longer count a Markdown partial as an unlinted page.
    • Search results no longer show a code block’s title and language joined to its first line.

create-nimbus-docs 0.8.0

Minor Changes

  • #273 352a245 Thanks @MohamedH1998! - A redesigned API reference:

    • The API home lists every endpoint, grouped by x-tagGroups, with a filter; large specs load in parts as you scroll. The API route serves the later parts at /api/index/2/ and on, noindex and left out of the sitemap and search; it takes the part size as homeChunkSize in both getApiStaticPaths and getApiRoute (without it, the home is one page), and getApiRoute returns the parts as home.
    • Section pages list their endpoints name first, with the method and path beneath.
    • The API version picker sits in the header, at every width.
    • Code rail lines sit on whole pixels, with quieter line numbers; section titles are in full ink.
    • The API sidebar’s rows match the docs sidebar’s.
    • Section page operations gain method, path, description and deprecated, and the root page gains an index of every endpoint.
    • getApiRoot reads an API version’s root page from any route; chunkApiIndex and apiIndexRows split and flatten its index.

    nimbus-docs migrate lists the optional steps to adopt it.

  • #274 961e85d Thanks @MohamedH1998! - - New sites’ share cards show the site’s logo, the page’s section and its title, on white. A long title shrinks before it’s cut and stays within three lines.

    • The card’s look lives in the site’s src/pages/og/_card.ts; the logo is drawn once, in src/components/logo.ts, for the header and the cards.
    • @cloudflare/nimbus-docs/og fits text by measuring it and renders cards to PNG. It needs satori and @resvg/resvg-js, optional peers.
    • getPageSection(page) returns the label of a page’s nearest parent, from the sidebar for docs pages and from the spec for API pages.

  • #274 91eb2e9 Thanks @MohamedH1998! - - Card takes href: the whole card becomes the link.

    • Diagram buttons and controls keep their 32px height inside prose.
    • PUT and PATCH method chips meet 4.5:1 contrast in light mode.
    • The version picker and the API field toggle are named by their visible text.

  • #272 9a65f9f Thanks @MohamedH1998! - New sites start on the redesigned starter:

    • A fill-in Introduction as the home page, a Writing pages guide and a Components page replace the sample pages and the landing page.
    • A new type scale, steel accent, code blocks, sidebar and header logo.
    • One pagination bar for the previous and next pages; with focus in the bar, [ and ] move between them.
    • Every component part has a data-slot to style it by, except sidebar rows, which stay bare so large sidebars stay light.
    • Components wrap long words, URLs and labels instead of overflowing on phones.
    • Text meets 4.5:1 contrast in light mode, Steps are a real list, manual Tabs render one tab list and pair each tab with its panel.
    • Pages mirror correctly in right-to-left languages; code stays left to right.
    • On phones, sites with several sections show them as tabs under the header.
    • Thin, theme-coloured scrollbars.
    • PageActions renders extra actions passed as children; the layout passes the Copy MCP URL action that way.

    Existing sites keep their look. nimbus-docs migrate lists optional steps to adopt it, the lighter sidebar rows, and the new favicons and asset caching. The registry adds a variants lib that Badge and Button install with them.

  • #278 b6d4837 Thanks @MohamedH1998! - - Route files say how they render. nimbus-docs check reports each route Nimbus manages whose file disagrees with rendering, and check --fix rewrites it: the prerender line, getStaticPaths on built routes only, and the collection name in a collection route’s page helper. Without rendering, Nimbus builds every one of these routes ahead of time, a collection route such as src/pages/sdk/[...slug].astro included. rendering still wins at build, which now warns once and lists the files.

    • A built dynamic route with no getStaticPaths fails the build, naming the file; Astro can’t build it.
    • The page helpers take the collection as a second argument, such as getCollectionPage(Astro, "sdk") or getApiRoute(Astro, "api", { homeChunkSize }), so a request-rendered route needs no getStaticPaths to say which collection it serves. A route whose getStaticPaths and helper name different collections fails with nimbus/collection-route-mismatch.
    • add adapter-* updates route files after setting rendering, and its recipes run check --fix.
    • outdated and diff compare starter route files in the site’s own mode, so a route check --fix edited doesn’t read as a local change.
    • The starter’s Markdown, llms.txt and docs page routes drop export const prerender = true; the site’s output and rendering decide how they render. A scaffold with a server adapter writes its route files in the mode its rendering gives them.

  • #284 f256109 Thanks @MohamedH1998! - - A new site can include an API reference: --api adds one at /api, from your OpenAPI 3.x file (--api ./openapi.yaml) or a sample, and --template api makes it the whole site, at /. Without flags, the scaffolder asks what the site includes, and it refuses a spec that isn’t OpenAPI 3.x before writing anything.

    • AGENT.md in a site with an API reference says where its spec and route are; a site that is only the reference has no docs-writing sections.
    • The starter’s header shows Docs and API reference tabs when a site has an API reference beside its docs.

Patch Changes

  • #282 e983040 Thanks @MohamedH1998! - - The package READMEs describe Nimbus as the authoring tool for docs, with the CLI by task and the scaffolder’s options.

  • #244 17bf1ce Thanks @MohamedH1998! - - NIMBUS_BUILD_ONLY=docs-es builds one collection, or a comma-separated set, and leaves the others empty; dev, sync and check ignore it with one notice.

    • A slice without the docs collection writes its sitemap, search bundle, stylesheet, assets and llms-full.txt under its prefix, and drops the root files the root slice serves.
    • The root slice’s llms.txt lists every collection’s llms.txt, and search merges the other slices’ indexes at runtime.
    • nimbus-docs lint checks links into other slices against the previous build’s routes, as warnings.
    • A slice build fails on an unknown collection, and on docs version collections split across slices. Slices work under Astro’s base: every URL a slice serves and advertises is under it.
    • The route list nimbus-docs lint checks against reads _redirects where the Cloudflare adapter moves it when the site has a base, so redirects stay known to link checking.
    • searchIndex in virtual:nimbus/config names the search bundles as served URLs, base included. The starter’s search provider loads its slice’s bundle and merges the others.
    • A guide, “Build one locale or one part”, with the Worker and zone routes per slice and a workflow that builds the slice a pull request touched.

  • #285 d45764d Thanks @MohamedH1998! - - migrate’s redesigned-starter step lists src/components/logo.ts, which the new Logo.astro imports.

    • Search results for API pages keep an operation’s name, method and path apart, and no longer index the API home filter’s Retry button.

  • #287 8758eeb Thanks @MohamedH1998! - - lint and check accept relative links between a content source’s pages, which the build turns into page URLs.

    • Search in a slice of several collections skips the other collections’ bundles instead of failing. @cloudflare/nimbus-docs/client exports mergeSearchIndexes, which the starter’s search provider uses.
    • API operation pages keep field names, types and labels apart in search, and leave the expand controls out.
    • The search button’s accessible name starts with its visible label, and API pages name their sidebars.

  • #243 5604125 Thanks @MohamedH1998! - - agents: { mcp: true } serves a remote MCP server at /mcp with list_pages and get_page over the published Markdown, plus a Server Card at /mcp/server-card, a line in llms.txt and an entry in the AI catalog. It needs a server adapter and @modelcontextprotocol/server; nimbus-docs check reports a missing SDK.

    • Docs pages in the starter show a “Copy MCP URL” page action that copies the server URL when the server is on. On an existing site, run nimbus-docs diff src/components/ConnectMcp.astro --apply and nimbus-docs diff src/components/connect-mcp.client.ts --apply, then pass {capabilities.mcpUrl && <ConnectMcp />} to <PageActions> in src/layouts/DocsLayout.astro, as the Remote MCP server guide shows.

  • #287 8758eeb Thanks @MohamedH1998! - - add adapter-cloudflare on a pnpm site declines workerd’s build script first, so the install no longer fails.

    • A slice’s Markdown images are published under its prefix, and Markdown images load in astro dev.
    • WebMCP search covers every slice, like the search dialog. On an existing site, pass searchIndex to it as the starter’s WebMCP.astro does.
    • Search excerpts for request-rendered pages read as text, not Markdown syntax.
    • add --overwrite names the files that carry your edits.

  • #260 0c31e84 Thanks @MohamedH1998! - - add --overwrite without a terminal keeps components you’ve edited and exits 1; --overwrite --yes replaces them and says how many carried edits.

    • add a b installs both; an unknown slug stops before anything is installed.
    • check says an optional upgrade stays listed until migrate records the version as reviewed.
    • New pnpm sites build pages with local images: sharp is a starter dependency.
    • astro build --root <site> from another folder finds the social-card font.

nimbus-docs 0.18.1

Patch Changes

  • #247 b98bd3f Thanks @MohamedH1998! - - Generated _headers rules leave out any header the site’s own _headers already sets for that path, site-wide rules included, so hosts no longer send doubled values such as Access-Control-Allow-Origin: *, *.

  • #250 d664242 Thanks @sansynx! - Keep application warnings visible during concurrent OpenAPI specification publication.

  • #257 e9a4360 Thanks @MohamedH1998! - - New Cloudflare projects, and nimbus-docs add adapter-cloudflare when wrangler.jsonc has no valid date, get a compatibility_date the installed Workers runtime supports instead of today’s date, so local dev starts.

create-nimbus-docs 0.7.13

Patch Changes

  • #225 6832653 Thanks @MohamedH1998! - Use the matching PR registry in on-demand preview scaffolds.

  • #257 e9a4360 Thanks @MohamedH1998! - - New Cloudflare projects, and nimbus-docs add adapter-cloudflare when wrangler.jsonc has no valid date, get a compatibility_date the installed Workers runtime supports instead of today’s date, so local dev starts.

nimbus-docs 0.18.0

Minor Changes

  • #229 a04304c Thanks @MohamedH1998! - - A page or reusable snippet with only frontmatter builds, and its Markdown version is just its title and source.

    • A snippet included inside a list item or quote keeps that structure in the page’s Markdown version.
    • llms.txt names each section for its index page’s title, such as “Guides” instead of guides.
    • Documentation search results link to the page itself instead of a URL ending in #, and excerpts no longer include the page actions.
    • The Markdown version of an API page names each field as the page does, with its full coordinate beside it for citing.

  • #232 d655e86 Thanks @MohamedH1998! - - API pages link to the previous and next page in sidebar order, even when a group is collapsed.

    • Error responses start collapsed; a link to one, or to a field inside it, opens it.
    • A sidebar link to an API or docs-version mount, such as /api, no longer warns.
    • Operations that fall back to a coordinate route print one summary line, so other warnings stay visible.
    • Samples and the endpoint card keep a server URL’s query after the path.
    • Response toggles meet 4.5:1 contrast in light mode, field anchors work on touch screens, and “Authorisation” reads “Authorization”.

  • #211 4a841cb Thanks @MohamedH1998! - - Add bundle: false to an api entry to serve a very large or many-version API from static assets instead of the server bundle. Unchanged pages are shared across versions, and unchanged versions aren’t prepared again on rebuild. Needs src/live.config.ts registering apiPagesLoader from @cloudflare/nimbus-docs/live; the build shows the snippet. The build suggests the option when an API’s bundled page data passes 16 MiB.

    • Add getVersionSwitchUrl and getApiVersionHead for version pickers and heads in every rendering mode; the starter’s picker and API layout use them.

  • #212 94ebe52 Thanks @MohamedH1998! - API pages show the sidebar filter. With sidebar: "on-demand" it also finds pages the sidebar hasn’t loaded.

  • #222 e15eea7 Thanks @MohamedH1998! - New api[].extensions option: list the x-* fields to keep, and their values are copied onto API pages as page.extensions and field.extensions for your components to render.

  • #214 825ffcf Thanks @MohamedH1998! - API reference pages show the version picker for versioned APIs, in the sidebar and the mobile navigation.

  • #211 02f53a1 Thanks @MohamedH1998! - versionMode is now versionUrl: versionUrl: { in: "query" } selects the version with ?version= instead of ?api-version=, and old links redirect. Set param to use another name (review entry api-version-url).

  • #240 381b37a Thanks @MohamedH1998! - - og:image:width and og:image:height describe the image: generated cards stay 1200 × 630, a socialImage file in public/ is measured at build time, and any other image gets no size tags. NimbusHead takes socialImageSize to set them for an image Nimbus can’t measure.

    • The sitemap has <lastmod> on every documentation page, from frontmatter lastUpdated or the page’s last commit, and /sitemap.xml is a copy of sitemap-index.xml unless the site serves its own.
    • The starter’s BaseLayout passes socialImageSize through to NimbusHead, and the 404 page recipe writes the new title and noindex.
    • On a shallow clone, pages get no git dates instead of the wrong one, and the build says how to fetch the history.
    • The 404 page’s title is Page not found | <site> and the page is noindex.

  • #233 1f2ce43 Thanks @MohamedH1998! - - New sites open content images at full size on click. On an existing site, run nimbus-docs add image-zoom and render <ImageZoom /> in src/layouts/DocsLayout.astro.

  • #238 315ab66 Thanks @MohamedH1998! - - A resource-action-v2 route convention publishes tag pages at lowercase URLs, such as /api/tags/user-management, with the same operation URLs as resource-action-v1. Existing conventions, and sites without routes, are unchanged.

    • The API reference recipe sets resource-action-v2 on new sites and resolves the route collisions the build reports.

  • #224 79b05ef Thanks @MohamedH1998! - - New markdown.features option turns on Sätteri syntax, such as { headingAttributes: true } for ## Install {#install} or { math: true }. Pages, generated Markdown, reusable snippets and lint all follow it. New sites start with heading ids on.

    • Generated Markdown drops {/* comments */}.
    • Invalid MDX reports the file, line and fix instead of an internal error.

  • #226 dd95e97 Thanks @MohamedH1998! - - New math() Markdown plugin typesets $…$, $$…$$ and ```math at build time as native MathML, with no math JavaScript. Add math() to markdown.hastPlugins and math: true to markdown.features to use it.

  • #236 fb759c5 Thanks @MohamedH1998! - - With the section route at src/pages/[...section]/llms.txt.ts, each sub-folder gets its own llms.txt, and its parent’s index links to it under “Sections”. New sites have this route; a [section] route keeps today’s one index per top-level section.

    • An llms-full.txt over 25 MiB becomes an index of one llms-full.txt per section, split further where a section is still too big, so the site deploys to Cloudflare.
    • LlmsEndpointReference (from @cloudflare/nimbus-docs/agent-endpoints) adds surface: "full" on section references, for the per-section llms-full.txt files.

  • #224 79b05ef Thanks @MohamedH1998! - Starter fixes:

    • The theme toggle no longer submits a surrounding form, reports its state to screen readers, and still switches when storage is blocked.
    • Closing a dialog no longer releases another overlay’s scroll lock.
    • “Copy page” works in Safari, and a failed command copy shows it failed.
    • In search, Enter on the close button closes the dialog, and status messages are announced.
    • <Render> params can’t replace registered components; small fixes to breadcrumbs and the mobile table of contents.
    • Banner content is rendered as written, like the rest of the site’s content.

  • #223 c39fdfc Thanks @MohamedH1998! - The docs version picker no longer appears on pages outside the docs versions, such as API reference and blog pages.

Patch Changes

  • #228 6d4bd68 Thanks @MohamedH1998! - - add reports components whose files already match the registry as up to date, and --overwrite lists each file it replaces, asking first in a terminal when you’ve edited the component.

    • add --overwrite detects edits to components that came with the starter from the starter release your site came from, so it replaces untouched ones without asking.
    • add adds a component’s missing files even when it keeps your edited ones, and lists each file it adds, replaces or keeps.
    • add no longer suggests registering a component that components.ts already registers.
    • Upgrade reviews about API reference pages are skipped on sites without an API collection.
    • outdated says when a newer Nimbus is out, when the reviewed version only needs recording, and when a registry dependency is installed below the version a component needs.
    • diff --apply on a file only you changed reports there’s nothing to pull, without failing.
    • diff, outdated and migrate explain preview builds instead of asking for a baseline.

  • #219 942c57b Thanks @MohamedH1998! - Generated code samples for multipart/form-data request bodies now send every part, with file fields as <name> placeholders, instead of only the Content-Type header.

  • #223 c39fdfc Thanks @MohamedH1998! - - Generated API samples use <base-url> when a spec has no server or a relative one, instead of an invented host, and fill server variables from their defaults.

    • OpenAPI 3.2 tag parent no longer prints a warning for each tag that uses it.
    • nimbus-docs add api-layout ends by pointing to the API route instead of src/components.ts.
    • The Markdown version of an API page fences cURL samples as bash.

  • #220 cd7f0da Thanks @MohamedH1998! - - Request field lists no longer show properties marked readOnly across schema alternatives, and response field lists no longer show those marked writeOnly across alternatives. Synthesized examples use the selected alternative; authored examples retain their values. Webhook payloads read like responses. Cite a readOnly field under the response.

    • A string example under a non-JSON media type such as application/x-ndjson is sent verbatim in generated samples.
    • Object form examples with media-type parameters such as ; charset=utf-8 generate per-field samples; authored encoded strings keep their bytes.

  • #234 1b546af Thanks @MohamedH1998! - - astro dev and astro check no longer delete the build’s page-collection list, so nimbus-docs check runs its page-collection checks after a build.

    • nimbus-docs lint and check say when the lint rules in your Astro config changed since .nimbus/lint.json was written, and to run astro sync.
    • check marks a scope that skipped some checks ◐ ok, partly checked, and says --types covers .ts and .tsx files only (run astro check for .astro).
    • nimbus-docs check --help lists check’s own flags.
    • The adapter warning for @astrojs/cloudflare 14.2.x says only a cold astro dev can fail; builds aren’t affected.
    • An invalid API spec, such as Swagger 2.0, fails the build with its message and no stack trace.
    • Request-rendered routes that export getStaticPaths() get one line explaining that the rendering policy renders them on request.
    • On a static Cloudflare site with trailingSlash: "always" and build.format: "file", the build and check warn that every /page/ link redirects, and name the wrangler.jsonc fix.
    • Repeated API spec warnings that differ only by source print once, with a count.
    • lint --rule nimbus/mdx-syntax says the syntax check always runs.

  • #211 ff1cd57 Thanks @MohamedH1998! - Load @iconify-json icon sets from the site root, so a build started from another directory still finds them.

  • #237 7a07851 Thanks @MohamedH1998! - - Search is indexed however astro build is started, including ./node_modules/.bin/astro build.

    • A site’s pagefind.yml applies when the build starts from another folder with --root.
    • The build says to install Pagefind only when it isn’t installed.

  • #230 25d21cf Thanks @MohamedH1998! - - Server scaffolds for Node, Vercel, and Netlify render docs pages on request, so Markdown negotiation works on them.

    • Scaffold into . or an empty folder, including a freshly cloned repository.
    • New repositories get a first commit; scaffolding inside an existing repository no longer creates a nested one.
    • npm create installs a handful of packages instead of the whole framework.
    • A missing package manager fails before anything is written, and a mistyped flag suggests the right one.
    • Yarn sites ignore .yarn/ the way Yarn recommends, and pin Yarn inside a folder that pins another package manager.
    • The starter’s AGENT.md explains sidebar groups, order, and links.
    • nimbus-docs check and --help show commands for your package manager.

  • #213 7350707 Thanks @MohamedH1998! - When an API’s spec can’t be published because a $ref isn’t a reference string, the build warning names where it is instead of printing [object Object].

  • #227 ea8712d Thanks @sansynx! - Add UTF-8 Content-Type headers for prerendered llms indexes, full documents, page Markdown, and robots.txt. Keep rules scoped to Nimbus file paths and preserve explicit owner Content-Type policies.

create-nimbus-docs 0.7.12

Patch Changes

  • #229 a04304c Thanks @MohamedH1998! - - A page or reusable snippet with only frontmatter builds, and its Markdown version is just its title and source.

    • A snippet included inside a list item or quote keeps that structure in the page’s Markdown version.
    • llms.txt names each section for its index page’s title, such as “Guides” instead of guides.
    • Documentation search results link to the page itself instead of a URL ending in #, and excerpts no longer include the page actions.
    • The Markdown version of an API page names each field as the page does, with its full coordinate beside it for citing.

  • #232 d655e86 Thanks @MohamedH1998! - - API pages link to the previous and next page in sidebar order, even when a group is collapsed.

    • Error responses start collapsed; a link to one, or to a field inside it, opens it.
    • A sidebar link to an API or docs-version mount, such as /api, no longer warns.
    • Operations that fall back to a coordinate route print one summary line, so other warnings stay visible.
    • Samples and the endpoint card keep a server URL’s query after the path.
    • Response toggles meet 4.5:1 contrast in light mode, field anchors work on touch screens, and “Authorisation” reads “Authorization”.

  • #211 4a841cb Thanks @MohamedH1998! - - Add bundle: false to an api entry to serve a very large or many-version API from static assets instead of the server bundle. Unchanged pages are shared across versions, and unchanged versions aren’t prepared again on rebuild. Needs src/live.config.ts registering apiPagesLoader from @cloudflare/nimbus-docs/live; the build shows the snippet. The build suggests the option when an API’s bundled page data passes 16 MiB.

    • Add getVersionSwitchUrl and getApiVersionHead for version pickers and heads in every rendering mode; the starter’s picker and API layout use them.

  • #212 94ebe52 Thanks @MohamedH1998! - API pages show the sidebar filter. With sidebar: "on-demand" it also finds pages the sidebar hasn’t loaded.

  • #214 825ffcf Thanks @MohamedH1998! - API reference pages show the version picker for versioned APIs, in the sidebar and the mobile navigation.

  • #240 381b37a Thanks @MohamedH1998! - - og:image:width and og:image:height describe the image: generated cards stay 1200 × 630, a socialImage file in public/ is measured at build time, and any other image gets no size tags. NimbusHead takes socialImageSize to set them for an image Nimbus can’t measure.

    • The sitemap has <lastmod> on every documentation page, from frontmatter lastUpdated or the page’s last commit, and /sitemap.xml is a copy of sitemap-index.xml unless the site serves its own.
    • The starter’s BaseLayout passes socialImageSize through to NimbusHead, and the 404 page recipe writes the new title and noindex.
    • On a shallow clone, pages get no git dates instead of the wrong one, and the build says how to fetch the history.
    • The 404 page’s title is Page not found | <site> and the page is noindex.

  • #233 1f2ce43 Thanks @MohamedH1998! - - New sites open content images at full size on click. On an existing site, run nimbus-docs add image-zoom and render <ImageZoom /> in src/layouts/DocsLayout.astro.

  • #224 79b05ef Thanks @MohamedH1998! - - New markdown.features option turns on Sätteri syntax, such as { headingAttributes: true } for ## Install {#install} or { math: true }. Pages, generated Markdown, reusable snippets and lint all follow it. New sites start with heading ids on.

    • Generated Markdown drops {/* comments */}.
    • Invalid MDX reports the file, line and fix instead of an internal error.

  • #236 fb759c5 Thanks @MohamedH1998! - - With the section route at src/pages/[...section]/llms.txt.ts, each sub-folder gets its own llms.txt, and its parent’s index links to it under “Sections”. New sites have this route; a [section] route keeps today’s one index per top-level section.

    • An llms-full.txt over 25 MiB becomes an index of one llms-full.txt per section, split further where a section is still too big, so the site deploys to Cloudflare.
    • LlmsEndpointReference (from @cloudflare/nimbus-docs/agent-endpoints) adds surface: "full" on section references, for the per-section llms-full.txt files.

  • #216 647471a Thanks @sansynx! - Keep version-switcher entries exposed as navigation links, with the current page identified by aria-current, instead of listbox options

  • #230 25d21cf Thanks @MohamedH1998! - - Server scaffolds for Node, Vercel, and Netlify render docs pages on request, so Markdown negotiation works on them.

    • Scaffold into . or an empty folder, including a freshly cloned repository.
    • New repositories get a first commit; scaffolding inside an existing repository no longer creates a nested one.
    • npm create installs a handful of packages instead of the whole framework.
    • A missing package manager fails before anything is written, and a mistyped flag suggests the right one.
    • Yarn sites ignore .yarn/ the way Yarn recommends, and pin Yarn inside a folder that pins another package manager.
    • The starter’s AGENT.md explains sidebar groups, order, and links.
    • nimbus-docs check and --help show commands for your package manager.

  • #224 79b05ef Thanks @MohamedH1998! - Starter fixes:

    • The theme toggle no longer submits a surrounding form, reports its state to screen readers, and still switches when storage is blocked.
    • Closing a dialog no longer releases another overlay’s scroll lock.
    • “Copy page” works in Safari, and a failed command copy shows it failed.
    • In search, Enter on the close button closes the dialog, and status messages are announced.
    • <Render> params can’t replace registered components; small fixes to breadcrumbs and the mobile table of contents.
    • Banner content is rendered as written, like the rest of the site’s content.

  • #223 c39fdfc Thanks @MohamedH1998! - The docs version picker no longer appears on pages outside the docs versions, such as API reference and blog pages.

nimbus-docs 0.17.0

Minor Changes

  • #204 a8e0d02 Thanks @MohamedH1998! - - Agent files follow the rendering policy: a page’s index.md/index.mdx renders in its collection’s mode, a section’s llms.txt in the mode of the collection it lists, llms.txt/llms-full.txt in rendering.default, and homepage Markdown in the root collection’s mode. Mounted collections get their own agent routes, copied starter routes keep working unchanged, and static sites don’t change.

  • #201 855091c Thanks @MohamedH1998! - Add samples.generate to choose which languages Nimbus generates code samples in, and fix generated samples and examples that sent different values from the page.

    • samples.generate: set samples: { generate: ["curl"] } on an api entry to generate only a cURL request, instead of cURL, TypeScript, and Python, on every operation. [] generates none, so operations show only their authored x-codeSamples. The default is unchanged: all three. samples.keepGenerated still picks the generated languages shown next to authored samples; each of its languages must now also be in generate.
    • Python and TypeScript bodies: in Python, a string containing a newline, carriage return, or tab no longer breaks the sample with a SyntaxError, and object keys with quotes or backslashes stay valid. In both languages, a backslash is no longer read as an escape (C:\\temp\\new was sent with a tab and a newline), including in text bodies such as text/plain. A JSON body of false, 0, or "" is now sent instead of dropped.
    • cURL bodies: a body containing ' was passed through an unquoted heredoc, so the shell collapsed backslashes and ran $NAME and backticks in the example when the sample was pasted. The heredoc is now quoted.
    • Form bodies: application/x-www-form-urlencoded bodies were dropped from every sample and are now sent in all three languages. A property with an encoding entry follows OpenAPI: style, explode, or allowReserved select query-style serialization, and an entry without them sends the value as its contentType, so an object is sent as JSON. A property without an entry nests objects in brackets (metadata[plan]=pro), repeats the name for each item of a scalar array (tags=a&tags=b), and indexes arrays of objects (items[0][price]=p_1). A string example is read as an encoded form; a form example with no fields sends no body. multipart/form-data bodies are still omitted.
    • Form encoding: explicit JSON content types serialize scalar values as JSON before form encoding. allowReserved: true preserves valid percent-encoded triples and safe reserved characters without double encoding; form delimiters and unsafe characters remain encoded.
    • cURL text bodies: a body starting with @ is sent as text instead of uploading the file it names.
    • Joined form values: a ,, |, or space inside an array item no longer reads as a separator with explode: false, unless allowReserved: true leaves a , unencoded.
    • Empty form field names: cURL now sends =value like the other languages.
    • Request example: an operation without code samples, such as with samples.generate: [], shows its request example on the page.
    • Swagger 2.0: a Swagger 2.0 document now fails the build with Swagger 2.0 isn't supported. Convert it to OpenAPI 3.x first. and the document’s path, instead of building pages with no server URL, unknown parameter types, and missing response schemas. The API reference docs show how to convert one before each build.

    If the installed httpsnippet writes a body differently from the layout Nimbus corrects, that language’s sample is left out rather than shown with an unescaped body. Authored x-codeSamples are unchanged. New sites scaffolded by create-nimbus-docs use this release.

  • #207 d77ff08 Thanks @MohamedH1998! - - A request-rendered API family can set versionMode: "query": one URL per operation, the version in ?api-version= (absent means the default, unknown is 404, hidden versions reachable by query only). Generated same-version links carry the query; discovery covers the default version at version-free URLs; non-default pages are noindex with the default counterpart as canonical. Path mode stays the default and is unchanged.

    • API version ids may contain dots, and must start and end with a letter or digit. An id like -v1 or v1- now fails validation; rename it.

  • #198 86b573a Thanks @MohamedH1998! - - Skills in skills/<name>/SKILL.md folders are published at /.well-known/agent-skills/ with a discovery index, archives for multi-file skills, and digests.

  • #199 b8a8dbd Thanks @MohamedH1998! - - Sites with API collections publish every spec, including hidden versions, as one self-contained openapi.json at its mount path, and list each visible API in an RFC 9727 catalog at /.well-known/api-catalog. Set publishSpec: false to keep a spec private.

  • #195 b685092 Thanks @MohamedH1998! - - Add discovery files, homepage Markdown, and Link headers to all sites.

    • Add editable Content Signals to the starter’s robots.txt.

  • #205 7b76521 Thanks @MohamedH1998! - - Sidebar groups are native details/summary with one class per row type, a CSS caret, and no animation; a group’s landing page lists as an “Overview” child row. Each page renders one sidebar tree, shared by the desktop rail and the mobile drawer, and a large sidebar’s page HTML drops by roughly 80%. The state scripts drive the old copied markup too.

  • #203 62d7956 Thanks @MohamedH1998! - - Only collections made with Nimbus’s helpers (docsCollection(), componentsCollection(), withNimbusMarkdown()) become pages; every other collection is plain Astro data with no naming rule, and the _ prefix convention is removed. If rendering is set, a site’s own page collection with a catch-all route now needs an entry in rendering.collections.

  • #196 2e200ce Thanks @MohamedH1998! - - The starter registers a search_documentation WebMCP tool, backed by the site’s Pagefind index.

  • #200 c17a945 Thanks @MohamedH1998! - - On server output, a request-rendered page returns its Markdown when the request prefers text/markdown; the URL stays canonical and both forms send Vary: Accept.

    • The starter homepage renders on request when a collection already does under server output, so it negotiates too. All-build homepages remain prerendered in production.
    • Preserve owner static-header rules while adding discovery fields, and support prose request rendering and published Markdown negotiation through Astro adapters and standard HTTP on non-Cloudflare deployments.
    • Recreate the isolated browser-agent Pagefind instance after observable search failures and give accurate connection/reload guidance. Pagefind’s swallowed index-chunk failures remain a documented upstream limitation.
    • Include a release-matched agent-interface guide in the framework package and point generated project instructions to it.

Patch Changes

  • #201 7b8c3e8 Thanks @MohamedH1998! - For methods that support request bodies, preserve JSON null in generated TypeScript and Python samples. They now send the same four-byte JSON payload as cURL instead of omitting it. Absent request bodies remain absent, and schema-derived examples and authored code samples keep their existing behavior.

  • #193 bcc1b1e Thanks @sansynx! - Keep synced tabs usable when browser storage writes fail because the storage quota is full.

  • #206 bcfe446 Thanks @MohamedH1998! - - The version picker keeps a reader on the same operation when its operationId changed between versions but its HTTP method and path shape did not (including a renamed path parameter). The pairing is order-independent and never guesses: anything ambiguous stays unmatched and goes to the version landing, as before.

create-nimbus-docs 0.7.11

Patch Changes

  • #204 a8e0d02 Thanks @MohamedH1998! - - Agent files follow the rendering policy: a page’s index.md/index.mdx renders in its collection’s mode, a section’s llms.txt in the mode of the collection it lists, llms.txt/llms-full.txt in rendering.default, and homepage Markdown in the root collection’s mode. Mounted collections get their own agent routes, copied starter routes keep working unchanged, and static sites don’t change.

  • #201 855091c Thanks @MohamedH1998! - Add samples.generate to choose which languages Nimbus generates code samples in, and fix generated samples and examples that sent different values from the page.

    • samples.generate: set samples: { generate: ["curl"] } on an api entry to generate only a cURL request, instead of cURL, TypeScript, and Python, on every operation. [] generates none, so operations show only their authored x-codeSamples. The default is unchanged: all three. samples.keepGenerated still picks the generated languages shown next to authored samples; each of its languages must now also be in generate.
    • Python and TypeScript bodies: in Python, a string containing a newline, carriage return, or tab no longer breaks the sample with a SyntaxError, and object keys with quotes or backslashes stay valid. In both languages, a backslash is no longer read as an escape (C:\\temp\\new was sent with a tab and a newline), including in text bodies such as text/plain. A JSON body of false, 0, or "" is now sent instead of dropped.
    • cURL bodies: a body containing ' was passed through an unquoted heredoc, so the shell collapsed backslashes and ran $NAME and backticks in the example when the sample was pasted. The heredoc is now quoted.
    • Form bodies: application/x-www-form-urlencoded bodies were dropped from every sample and are now sent in all three languages. A property with an encoding entry follows OpenAPI: style, explode, or allowReserved select query-style serialization, and an entry without them sends the value as its contentType, so an object is sent as JSON. A property without an entry nests objects in brackets (metadata[plan]=pro), repeats the name for each item of a scalar array (tags=a&tags=b), and indexes arrays of objects (items[0][price]=p_1). A string example is read as an encoded form; a form example with no fields sends no body. multipart/form-data bodies are still omitted.
    • Form encoding: explicit JSON content types serialize scalar values as JSON before form encoding. allowReserved: true preserves valid percent-encoded triples and safe reserved characters without double encoding; form delimiters and unsafe characters remain encoded.
    • cURL text bodies: a body starting with @ is sent as text instead of uploading the file it names.
    • Joined form values: a ,, |, or space inside an array item no longer reads as a separator with explode: false, unless allowReserved: true leaves a , unencoded.
    • Empty form field names: cURL now sends =value like the other languages.
    • Request example: an operation without code samples, such as with samples.generate: [], shows its request example on the page.
    • Swagger 2.0: a Swagger 2.0 document now fails the build with Swagger 2.0 isn't supported. Convert it to OpenAPI 3.x first. and the document’s path, instead of building pages with no server URL, unknown parameter types, and missing response schemas. The API reference docs show how to convert one before each build.

    If the installed httpsnippet writes a body differently from the layout Nimbus corrects, that language’s sample is left out rather than shown with an unescaped body. Authored x-codeSamples are unchanged. New sites scaffolded by create-nimbus-docs use this release.

  • #207 d77ff08 Thanks @MohamedH1998! - - A request-rendered API family can set versionMode: "query": one URL per operation, the version in ?api-version= (absent means the default, unknown is 404, hidden versions reachable by query only). Generated same-version links carry the query; discovery covers the default version at version-free URLs; non-default pages are noindex with the default counterpart as canonical. Path mode stays the default and is unchanged.

    • API version ids may contain dots, and must start and end with a letter or digit. An id like -v1 or v1- now fails validation; rename it.

  • #195 b685092 Thanks @MohamedH1998! - - Add discovery files, homepage Markdown, and Link headers to all sites.

    • Add editable Content Signals to the starter’s robots.txt.

  • #205 7b76521 Thanks @MohamedH1998! - - Sidebar groups are native details/summary with one class per row type, a CSS caret, and no animation; a group’s landing page lists as an “Overview” child row. Each page renders one sidebar tree, shared by the desktop rail and the mobile drawer, and a large sidebar’s page HTML drops by roughly 80%. The state scripts drive the old copied markup too.

  • #203 62d7956 Thanks @MohamedH1998! - - Only collections made with Nimbus’s helpers (docsCollection(), componentsCollection(), withNimbusMarkdown()) become pages; every other collection is plain Astro data with no naming rule, and the _ prefix convention is removed. If rendering is set, a site’s own page collection with a catch-all route now needs an entry in rendering.collections.

  • #196 2e200ce Thanks @MohamedH1998! - - The starter registers a search_documentation WebMCP tool, backed by the site’s Pagefind index.

  • #200 c17a945 Thanks @MohamedH1998! - - On server output, a request-rendered page returns its Markdown when the request prefers text/markdown; the URL stays canonical and both forms send Vary: Accept.

    • The starter homepage renders on request when a collection already does under server output, so it negotiates too. All-build homepages remain prerendered in production.
    • Preserve owner static-header rules while adding discovery fields, and support prose request rendering and published Markdown negotiation through Astro adapters and standard HTTP on non-Cloudflare deployments.
    • Recreate the isolated browser-agent Pagefind instance after observable search failures and give accurate connection/reload guidance. Pagefind’s swallowed index-chunk failures remain a documented upstream limitation.
    • Include a release-matched agent-interface guide in the framework package and point generated project instructions to it.

  • Updated dependencies [a8e0d02, 855091c, d77ff08, 86b573a, b8a8dbd, b685092, 7b8c3e8, 7b76521, 62d7956, 2e200ce, c17a945, bcc1b1e, bcfe446]:

    • @cloudflare/nimbus-docs@0.17.0

nimbus-docs 0.16.0

Minor Changes

  • #191 18b0005 Thanks @MohamedH1998! - Generated API code samples show <name>, such as <account_id>, for a path parameter unless a value declared in its schema produces the generated value, instead of a guess such as string, 0, or a made-up UUID. This holds for any schema shape, including allOf, unions, and if/then. Required query parameters and headers keep the generated value, guesses included; one with no schema, or whose generated value is an array or object, now shows <name> instead of its bare name. A parameter’s own example or examples now wins over its schema, as OpenAPI specifies. Credential placeholders now say what goes there: Bearer <token>, Basic <credentials>, and the API key’s name, such as <X-API-Key>. Placeholders render unencoded in every language, including names that URL encoding would change, such as filter[name]. Declared values, including ones that look like a placeholder, and request bodies are unchanged.

    Every authored x-codeSamples entry is now kept, including several with the same lang; previously only the first entry per language was shown. Each sample has an id, unique within the operation: the language for the first sample in that language, then python-2, python-3. A repeated label, or a missing one that falls back to lang, is numbered for display (Python (2)) in the picker and the Markdown version. To give each of them its own picker option, update the api-code-rail registry component with nimbus-docs add api-code-rail, choosing Overwrite for its two files; see the upgrade entry api-code-sample-ids. Without the update, a language’s samples show one after another.

    Add samples.keepGenerated to api entries, so an operation with authored x-codeSamples can still show generated samples. Kept samples follow the authored ones, and an authored sample in the same language replaces the generated one. The default, [], keeps today’s behavior.

    api: [{ collection: "api", spec: "./src/api/openapi.yaml", samples: { keepGenerated: ["curl"] } }],

  • #190 9f54406 Thanks @MohamedH1998! - Breaking: API references no longer publish a page for each components/schemas entry. To keep schema pages, add schemaPages: true to the api entry; that restores today’s output exactly.

    With schema pages off (the new default), schemas still shape operation pages, including the properties previewed under each union variant, but get no page, Markdown version, OG image, sitemap, search, or llms.txt entry, or citation coordinate. Union variants, discriminator mappings, and map<Name> types render as text. A citation in your content to a schema or schema field fails the build and names the setting. Schema names still claim their schemas/<Name> routes, so turning pages on can’t collide with an operation. On a 400-operation slice of a large public spec, this cut output files by 60% and build time by more than half.

    getApiPageProps now throws for a coordinate that has no page, such as a schema with schema pages off or an x-tagGroups category, instead of returning the API root’s URLs as if they were its own.

  • #181 71ff242 Thanks @MohamedH1998! - Add sidebar to api entries, so large API references stop putting the whole navigation tree in every page. "full" (the default) keeps today’s behavior. "on-demand" includes top-level items plus the current page’s branch. A collapsed group opens in place and loads its rows from its own page, where the sidebar lists them open; a group without a page, such as an x-tagGroups category, loads them from the API overview. Without JavaScript, a collapsed group’s label still links to its page. The mode is read from the api entry in the Nimbus config, including for sites that pass their entry to apiCollection({ … }).

    api: [{ collection: "api", spec: "./src/api/openapi.yaml", sidebar: "on-demand" }],

    ApiNavItem gains optional deferred and childrenHref fields. @cloudflare/nimbus-docs/client adds initNavSidebar(), and @cloudflare/nimbus-docs/runtime adds navStateScript, an inline script, and navBuildId, which a sidebar renders as data-nb-nav-build. Together they keep a sidebar’s open groups, loaded rows, and scroll position from page to page for the session, restored before the page paints and without replaying animations. Cached rows are tied to the build that rendered the page, so rows cached before a deployment are never shown after it, including on client-side navigation. apiCollection({ … }) warns when it sets a sidebar the config doesn’t match.

    A tag’s x-displayName now sets its label in the sidebar, page title, and breadcrumbs, while its name still decides its coordinate and route. This lets a spec group hundreds of flat tags under readable parents.

    Group pages now list their subsections (ApiSectionPage.sections), in HTML and Markdown, so every page stays reachable without the sidebar. The API overview no longer links an x-tagGroups category to itself: it lists the category’s member sections instead. Both changes apply in every sidebar mode.

    Starter components: ApiSidebarItem renders a deferred group as a closed group with an empty panel, and ApiLayout mounts initNavSidebar and the restore script for both the desktop rail and the mobile drawer. The API sidebar now keeps the groups a reader opened and its scroll position from page to page in every mode, and no longer fades or replays group animations during navigation. The mobile drawer moved ahead of the desktop rail in ApiLayout, so one inline script restores both before the page paints. ApiBody lists a group page’s subsections.

    Existing sites keep working unchanged with the default sidebar: "full". "on-demand" needs the new API components: with older ones, the build fails and names the outdated files. Update them with nimbus-docs add api-layout, choosing Overwrite for api-layout and api-sidebar. nimbus-docs add now warns when the registry serves components from a different release than the project’s @cloudflare/nimbus-docs.

  • #194 a14c58f Thanks @MohamedH1998! - nimbus/internal-link follows redirects:

    • Links through a working redirect pass. Nimbus reads the build’s _redirects and Astro’s redirects; the new redirectsFile integration option adds a redirects file your deployment reads under another name. A redirect to a page that doesn’t exist is still a broken link.
    • Redirects match the way your platform matches them: Netlify’s rules with a netlify.toml, Cloudflare’s otherwise.
    • New nimbus/redirected-link rule (off by default) reports links that go through a permanent redirect, with the URL to use instead.
    • Run astro build again after upgrading: .nimbus/routes.json has a new version.

Patch Changes

  • #185 11e6d85 Thanks @MohamedH1998! - Static API pages color their code samples again. _nimbus/shiki.css now defines every token class the pages use; it used to miss the classes only API samples used, so on a site with only API pages, every sample rendered without color.

  • #187 278a3ff Thanks @MohamedH1998! - nimbus/internal-link can now gate CI:

    • .nimbus/routes.json lists every file the build produced, so links to /llms.txt, feeds, .md alternates, and public/ files no longer show as broken.
    • When the rule is on and .nimbus/routes.json is missing, isn’t valid JSON, or was written by another version of Nimbus, nimbus-docs lint reports one error on that file and exits 1, instead of skipping the rule. When astro build starts, it deletes the previous build’s file, or marks it incomplete if it can’t be deleted, so lint never accepts it after a failed build. If the file can be neither deleted nor changed, the build fails until its permissions are fixed. Run astro build before nimbus-docs lint. nimbus-docs check is unchanged: a missing file is still a note there, not an error.
    • nimbus-docs lint exits 1 when .nimbus/lint.json is missing, instead of reporting a clean run with every rule off. Run astro build or astro dev first; they write the rules from your Astro config there. --rule <code> still runs that one rule without it.
    • A bare relative link such as [CLI](cli) now counts as a relative link, like ./cli, instead of being looked up as /cli.
    • Some lint runs that passed before now fail. Links that include Astro’s base (for example /docs/guide under base: "/docs") used to pass, but Nimbus adds the base again when the page renders, so they lead to /docs/docs/guide, a 404. Lint now reports them and suggests the link without the base. To fix them, remove the base from the link. Write ignore patterns without the base too.

  • #183 e5fe9f3 Thanks @MohamedH1998! - - Generated Markdown (.md pages and llms-full.txt) is built from the parsed MDX, so it keeps the structure the HTML page shows: code blocks and nested lists stay in their list items, components stay inside the list item, card, or blockquote that holds them, and nested components keep their own content.

    • Components without a Markdown renderer no longer leave raw tags.
    • Text MDX reads differently from Markdown, such as an indented line or an over-indented fence, is written so it reads the same.
    • import and export lines no longer appear in generated Markdown.

  • #186 aff3e9f Thanks @MohamedH1998! - - A markdown.componentMap renderer’s output goes into generated Markdown as written again (apart from surrounding whitespace), unless it uses another component, which still converts. In a table cell or a sentence, output with a line break or | is converted so the cell or sentence stays whole.

    • A page whose MDX can’t be parsed for generated Markdown keeps its text there, with a warning, instead of failing the build.

  • #182 9d2051c Thanks @MohamedH1998! - - outdated and diff also compare AGENT.md, CLAUDE.md, and tsconfig.json with the upstream starter, so upgraded sites get guidance fixes. Files every site rewrites, such as package.json, are never compared.

    • diff <file> --apply records the tag it took the file from in nimbus.json (templatesTagByFile), so the file no longer shows as a hand-merge after the next upstream change.
    • Each command rejects flags it doesn’t read. Before, outdated --cwd site ignored --cwd and checked the current directory. Scripts that pass an ignored flag now exit 1.
    • check and add adapter-cloudflare use @astrojs/cloudflare@~14.3.0. pnpm saved the old >=14.3.0 <14.4.0 as ^14.3.x, which allows 14.4.
    • add and init print plain lines without a terminal, instead of spinner escapes.
    • A duplicate page or unknown MDX component fails the build without a stack trace.

create-nimbus-docs 0.7.10

Patch Changes

  • #191 11ebb39 Thanks @MohamedH1998! - The api-code-rail component keys its sample picker by sample id, so several samples in one language each get their own option. It remembers the reader’s language, not the exact sample: a saved language opens that language’s first sample, and the choice syncs across open tabs. ?lang= accepts a sample id or a language. With packages before 0.16.0, which give samples no id, the picker keys by language as before.

    api-code-rail is distributed through the registry, not the scaffolded template. Existing sites update it with nimbus-docs add api-code-rail, choosing Overwrite for ApiCodeRail.astro and code-rail.client.ts.

  • #189 5c96da8 Thanks @MohamedH1998! - Refinements to the starter’s API reference components:

    • Status and method colours are retuned. Method chips use a tint and a 25% line from the same palette (--nb-m-*-tint, --nb-m-*-line).
    • Field rows fold like code. A collapsed row ends in { 4 properties }; an open row shows { on its signature and } under its children, centred on the guide line. “required” sits before the brace and never wraps away from it.
    • Union fields drop the variant list from their type text, since the list below names each variant. The full names show as a tooltip on the field name.
    • Constraints and default share one line. Field rows no longer show examples, because the code rail’s request and response examples already include them. Long values wrap instead of widening the page.
    • The code rail’s response toggle is a compact segmented control, and the header and response rows share 8px insets.
    • LayerCard takes orientation="horizontal", which ApiEndpointCard uses. Badge gains an outline variant.
    • Medium weight replaces semibold, letter-spacing is removed, and hover states no longer animate colour.

  • #181 71ff242 Thanks @MohamedH1998! - Add sidebar to api entries, so large API references stop putting the whole navigation tree in every page. "full" (the default) keeps today’s behavior. "on-demand" includes top-level items plus the current page’s branch. A collapsed group opens in place and loads its rows from its own page, where the sidebar lists them open; a group without a page, such as an x-tagGroups category, loads them from the API overview. Without JavaScript, a collapsed group’s label still links to its page. The mode is read from the api entry in the Nimbus config, including for sites that pass their entry to apiCollection({ … }).

    api: [{ collection: "api", spec: "./src/api/openapi.yaml", sidebar: "on-demand" }],

    ApiNavItem gains optional deferred and childrenHref fields. @cloudflare/nimbus-docs/client adds initNavSidebar(), and @cloudflare/nimbus-docs/runtime adds navStateScript, an inline script, and navBuildId, which a sidebar renders as data-nb-nav-build. Together they keep a sidebar’s open groups, loaded rows, and scroll position from page to page for the session, restored before the page paints and without replaying animations. Cached rows are tied to the build that rendered the page, so rows cached before a deployment are never shown after it, including on client-side navigation. apiCollection({ … }) warns when it sets a sidebar the config doesn’t match.

    A tag’s x-displayName now sets its label in the sidebar, page title, and breadcrumbs, while its name still decides its coordinate and route. This lets a spec group hundreds of flat tags under readable parents.

    Group pages now list their subsections (ApiSectionPage.sections), in HTML and Markdown, so every page stays reachable without the sidebar. The API overview no longer links an x-tagGroups category to itself: it lists the category’s member sections instead. Both changes apply in every sidebar mode.

    Starter components: ApiSidebarItem renders a deferred group as a closed group with an empty panel, and ApiLayout mounts initNavSidebar and the restore script for both the desktop rail and the mobile drawer. The API sidebar now keeps the groups a reader opened and its scroll position from page to page in every mode, and no longer fades or replays group animations during navigation. The mobile drawer moved ahead of the desktop rail in ApiLayout, so one inline script restores both before the page paints. ApiBody lists a group page’s subsections.

    Existing sites keep working unchanged with the default sidebar: "full". "on-demand" needs the new API components: with older ones, the build fails and names the outdated files. Update them with nimbus-docs add api-layout, choosing Overwrite for api-layout and api-sidebar. nimbus-docs add now warns when the registry serves components from a different release than the project’s @cloudflare/nimbus-docs.

  • #182 9d2051c Thanks @MohamedH1998! - - Cloudflare server scaffolds depend on @astrojs/cloudflare@~14.3.0, matching check.

  • Updated dependencies [11e6d85, 18b0005, 9f54406, 71ff242, a14c58f, 278a3ff, e5fe9f3, aff3e9f, 9d2051c]:

    • @cloudflare/nimbus-docs@0.16.0

Type to search…

↑↓ navigate↵ selectEsc close