Skip to content
Nimbus

Changelog, page 2

Releases nimbus-docs 0.15.2 – create-nimbus-docs 0.7.5.

2026

nimbus-docs 0.15.2

Patch Changes

  • #179 8ded65b Thanks @MohamedH1998! - - migrate refuses to record a reviewed version when the project’s @cloudflare/nimbus-docs isn’t installed, and says to install dependencies. Before, npx @cloudflare/nimbus-docs migrate --yes in a fresh clone recorded the latest release while the lockfile installed an older one, and the build then failed with advice that failed too.
    • When nimbus.json records a version newer than the installed one, the build error says to install dependencies or upgrade, with the command, instead of suggesting migrate.
    • migrate --dry-run --diff with nothing pending prints the same result and next step as migrate --dry-run, instead of nothing.
    • Before the first install, check reports one “Dependencies aren’t installed” error with the install command, instead of offering to install pagefind and wrangler one at a time or reporting a TypeScript error. The command follows the site’s packageManager, lockfile, or pnpm-workspace.yaml / .yarnrc.yml, not the tool that ran the CLI, so a pnpm site checked with npx is told pnpm install.
    • After check --fix without a terminal, the footer names check --fix --yes for skipped installs, and says a value such as site needs editing by hand or an interactive terminal. Before, it only said to rerun check --fix “in a terminal”, even for installs.
    • check --help gives the same stop rule as the starter’s AGENT.md.
    • The nimbus/request-rendering-build-required note no longer claims a build resolves it. check doesn’t verify request-rendered pages; a passing production build is the gate.
    • Under trailingSlash: "always" with build.format: "file", canonical and og:url URLs keep the trailing slash, so they match page links and the sitemap.
    • <PackageManagers type="exec"> runs the project’s installed CLI with every package manager: pnpm nimbus-docs and yarn nimbus-docs for a scoped package, instead of pnpm @cloudflare/nimbus-docs.
    • The starter fixes search on sites whose base has no trailing slash, such as base: "/docs". Existing sites: run npx @cloudflare/nimbus-docs outdated, then diff src/components/ui/search/providers/pagefind.ts --apply.

create-nimbus-docs 0.7.9

Patch Changes

  • #179 8ded65b Thanks @MohamedH1998! - - Yarn 2+ scaffolds install. A site scaffolded with yarn dlx or yarn create pins that Yarn in package.json packageManager, and the install runs without yarn dlx’s Plug’n’Play hooks. Before, corepack ran Yarn 1, the install failed with Cannot find module 'pnpapi', and the suggested yarn install made a Yarn 1 project. --package-manager yarn pins Yarn too, when yarn in the new directory runs Yarn 2+.
    • A Yarn site created inside another Yarn project that doesn’t list it as a workspace gets its own empty yarn.lock and installs, instead of failing with “doesn’t seem to be part of the project”. A workspace member still installs as a member.
    • When Yarn holds back a release published in the last day (YN0016, its npmMinimalAgeGate setting), the install failure says so.
    • Yarn sites ignore .yarn/install-state.gz.
    • Search works on sites whose Astro base has no trailing slash, such as base: "/docs". Before, the dialog loaded /pagefind/pagefind.js instead of /docs/pagefind/pagefind.js and said “Search is available after a production build.” Existing sites can take the fix with npx @cloudflare/nimbus-docs diff src/components/ui/search/providers/pagefind.ts --apply.
    • The empty starter’s home page no longer adds a second H1 under its title.
    • The starter’s AGENT.md:
      • Its upgrade steps now pull in starter fixes with outdated and diff --apply.
      • Feature recipes run with add <feature-slug> --print.
      • The Cloudflare audit is split into static and server output (server sites have no assets.directory).
      • It says a server site’s check stays partial after a build, and what to do about an error with no fix.
    • The welcome page names @cloudflare/nimbus-docs/content.
  • Updated dependencies [8ded65b]:
    • @cloudflare/nimbus-docs@0.15.2

nimbus-docs 0.15.1

Patch Changes

  • #177 adb8efe Thanks @MohamedH1998! - Add the copy-prompt registry component. Run nimbus-docs add copy-prompt to install CopyPrompt, a one-line prompt with a Copy prompt button for readers to paste into an AI coding agent. New sites don’t include it by default.

  • #171 41376dd Thanks @MohamedH1998! - Fix upgrade checks and CLI guidance.

    Behavior changes

    • nimbus-docs check warns about the placeholder site instead of exiting 1, matching the build. A CI job that relied on check failing for an unset site needs its own check.
    • migrate --dry-run and migrate --json report passed and exit 0 when no migrations or required reviews remain and a baseline is recorded, including when no entries fall between the recorded and installed versions.

    Upgrades

    • Sites upgrading from before 0.13.0 with a custom loader on a collection Nimbus indexes now see the 0.13.0 withNimbusMarkdown() requirement in migrate and outdated.
    • outdated --json adds summary.requiredPackageApis, the required subset of summary.packageApis, and a warnings array. It warns when the compared starter needs a newer package than the project has, which also blocks diff --apply.
    • outdated and migrate use the same terms: migrations and upgrade reviews. migrate prints each outcome once, and declining its record prompt says how to record the baseline later.

    CLI

    • Upgrade and migrate hints, and the build errors that point at migrate or init, print a runnable command instead of a raw Node path or a bare nimbus-docs. pnpm and Yarn projects that declare the package get the local bin, such as pnpm nimbus-docs migrate. With --cwd, the command runs from the current directory and pins the project’s Nimbus version, such as npx @cloudflare/nimbus-docs@0.15.1 migrate --cwd 'site' --yes.
    • After check --fix without a terminal, the hint says what the remaining fixes need: a terminal for prompts, or --yes for installs.
    • check lists what it skipped when the api config or the rendering policy isn’t a plain literal, or when src/content.config.ts is missing.
    • lint --help lists the lint rules and the --color and --no-color flags.
    • add suggests registering only the component you asked for in src/components.ts, not its dependencies.

    Cloudflare

    • add adapter-cloudflare installs @astrojs/cloudflare 14.3, which fixes a crash on the first astro dev with a cold cache (“Dev server process exited before becoming ready”). Existing sites can upgrade with pnpm add @astrojs/cloudflare@~14.3.0.
    • add adapter-cloudflare names the policy it adds: rendering: { default: "request" }, which renders every collection on request. To render only API pages on request, set that policy before running the installer, which keeps an existing policy.

  • #178 fd53431 Thanks @MohamedH1998! - Behavior changes

    • The duplicate-route check uses a page’s frontmatter slug, so a.mdx with slug: b next to b.mdx now fails the build, as other duplicate routes do. Before, the collision went unreported and Astro served one of the two pages.
    • withBase("/", base) returns the base without a trailing slash, such as /docs, when page URLs have none: under trailingSlash: "never", or build.format: "file" with "ignore". Code that appends to the result or compares it with /docs/ needs updating.

    check and init

    • check warns when an installed Astro adapter is outside the range Nimbus supports, such as @astrojs/cloudflare 14.1, with the command that installs a supported version. It doesn’t change the version itself.
    • On a PR preview, check says which release to pass to migrate --from once you install a release, instead of repeating “run a build, then check again”.
    • init --force rebuilds only the component and install records. It keeps the rest of a valid nimbus.json: the reviewed baseline, the starter version and variant, a preview’s record, and the server-output opt-in. Before, it reset them, which brought back the “no reviewed upgrade baseline” build failure.

    build.format: "file" and base

    • With build.format: "file", canonical URLs and og:url no longer end in .html, pages get previous and next links, the sidebar marks the current page, and breadcrumbs show page titles instead of “Welcome.Html”.
    • With a base and no trailing slashes, the home link, “Home” breadcrumb, and 404 page link to /docs, matching the home page’s canonical URL, instead of /docs/.

    Routes and Markdown

    • In per-page .md files and llms-full.txt, a code block in a nested list item stays in the item, so the text after it no longer turns into code, and a code block in a numbered item no longer splits the list.
    • The version switcher and missing-page redirects find pages in folders with dots, such as 1.2.3/, without a slug, and section index pages such as guides/index.mdx. A previousSlug written as a file path, such as guides/index, names the section’s page.

  • #172 6637381 Thanks @MohamedH1998! - Make generated links, the sitemap, and Markdown output follow the site config.

    Behavior changes

    • Under the default trailingSlash: "ignore", api.ref citation links now end in /, like sidebar links and the canonical URL, in pages, per-page .md files, and llms-full.txt.
    • With trailingSlash: "ignore" and build.format: "file" or "preserve", generated links no longer end in /, so they reach the pages Astro builds.

    Links, sitemap, and routes

    • Sidebar, navigation, breadcrumb, pagination, and citation links, and the API reference’s sidebar, breadcrumbs, and type links, follow Astro’s trailingSlash and build.format. Under "never" they drop the slash, and API links no longer 404 under "always" or "never". With the default build.format, they match the canonical URL.
    • noindex: true pages are left out of the sitemap on sites without base, as they already were with base.
    • The docs schema accepts Astro’s slug frontmatter field, so a page in a 1.2.3/ folder can keep its dots: slug: 1.2.3/setup serves it at /1.2.3/setup/. The version switcher and missing-page redirects use the slug too.
    • API pages no longer return 500 (“missing prepared page data”) in astro dev after the Astro config switches to server output while the dev server is running, for example after add adapter-cloudflare.

    Generated Markdown

    • Per-page .md files and llms-full.txt keep the indentation of code blocks in MDX pages, so YAML and Python keep their meaning. Code inside <Aside> gets the > prefix on every line.
    • A citation inside a longer fence, such as a ```` fence that shows a example, stays literal, as does one in a fence opened on a list-item line (`-yaml`). That fence also stays inside its list item in the Markdown output.
    • <PackageManagers> Markdown includes the package for every type and matches the HTML commands. type="dlx" pkg="@cloudflare/nimbus-docs" args="list" now renders npx @cloudflare/nimbus-docs list instead of npx list.

  • #170 ae346f0 Thanks @MohamedH1998! - Prerelease versions, such as the PR previews published to pkg.pr.new, select the upgrade entries of the release they preview. Two prereleases of the same release no longer count as newer than each other, so recording one and installing another doesn’t fail the build.

create-nimbus-docs 0.7.8

Patch Changes

  • #176 3b3d33f Thanks @MohamedH1998! - New Cloudflare server sites install @astrojs/cloudflare 14.3, which fixes a crash on the first astro dev with a cold cache (“Dev server process exited before becoming ready”).

  • #177 adb8efe Thanks @MohamedH1998! - Add the copy-prompt registry component. Run nimbus-docs add copy-prompt to install CopyPrompt, a one-line prompt with a Copy prompt button for readers to paste into an AI coding agent. New sites don’t include it by default.

  • #173 60d0af3 Thanks @MohamedH1998! - - Templates used without the scaffolder include nimbus.json with the reviewed Nimbus version, so their builds no longer fail with “Nimbus has no reviewed upgrade baseline”.

    • npm, yarn, and bun sites no longer include pnpm-workspace.yaml.
    • Yarn sites get a .yarnrc.yml with nodeLinker: node-modules. Before, Yarn 2+ installed in Plug’n’Play mode, and the site failed to build or start the dev server.
    • Unknown --content and --package-manager values are rejected with the valid choices. Before, a typo such as --package-manager pnmp scaffolded a site with no install and still printed “Done”.
    • Without a terminal, the scaffolder lists every question it can’t ask, each with the flag that answers it, and suggests --yes, instead of failing with uv_tty_init returned EINVAL. Flags that answer every question, including --git or --no-git, work without --yes.
    • The starter’s AGENT.md points at the Icon component the starter uses, @cloudflare/nimbus-docs/components/Icon.astro, instead of astro-icon, and at @cloudflare/nimbus-docs/content for the docs schema. Its commands use npx @cloudflare/nimbus-docs, which runs the project’s installed version with any package manager.
    • The starter’s Getting Started page shows the create command.

  • #178 7d606e3 Thanks @MohamedH1998! - Behavior changes

    • A failed dependency install exits 1. The scaffolder keeps the project and prints the commands that finish the setup. Before, it printed “Done” and exited 0, so CI treated the site as ready.
    • Unknown flags, such as --output server, stop the scaffolder with the list of valid flags. Before, they were ignored and the site was scaffolded without them.
    • --git with --no-git, and --deploy with --adapter, stop the scaffolder. Before, --no-git won and --deploy was ignored with a warning.
    • A second directory argument stops the scaffolder. A leading --, as pnpm passes it through, is accepted, so pnpm dlx … -- my-docs --yes no longer ignores --yes.

    First run

    • yarn dlx with Yarn 2+ can scaffold from a PR preview. Yarn now extracts the package instead of keeping it in a zip, where the preview’s bundled templates couldn’t be read.
    • Pressing Enter at the directory prompt uses my-docs, as shown. Before, it failed with “Directory is required”.
    • bun’s install output no longer shows in the scaffolder’s output, and “Next steps” no longer has an empty line where the install command would be. An install’s own output shows only when it fails.
    • The empty starter ships one home page, src/content/docs/index.mdx, so its first nimbus-docs check no longer warns about a duplicate route at /. Before, a landing page shadowed it and linked to pages the empty starter doesn’t have.
    • The starter’s home page links to its pages through their entries, so the links follow trailingSlash and a card whose page you delete disappears instead of linking to a 404.
    • The starter’s AGENT.md says to set site before running check in a loop, and ends the loop when only fixes that need input remain, so an agent no longer loops on the placeholder site. It also says components can be imported in the .mdx file that uses them instead of registered.

  • Updated dependencies [adb8efe, 41376dd, fd53431, 6637381, ae346f0]:

    • @cloudflare/nimbus-docs@0.15.1

nimbus-docs 0.15.0

Minor Changes

  • #162 982a47d Thanks @MohamedH1998! - Register API collections from the Nimbus config. apiCollection() now takes no arguments and reads the api entry whose collection matches its key in src/content.config.ts, so each spec is declared once, in the inline Nimbus config in astro.config.ts:

    // astro.config.ts
const nimbusConfig = defineNimbusConfig({
  site: "https://example.com",
  title: "Example",
  api: [{ collection: "api", spec: "./src/api/openapi.yaml" }],
});

// src/content.config.ts
export const collections = {
  docs: defineCollection(docsCollection()),
  api: defineCollection(apiCollection()),
};

    The api-reference recipe now uses this shape and no longer creates nimbus.config.ts, so nimbus-docs check validates the whole config statically and add adapter-cloudflare edits rendering in place.

    A collection key with no api entry fails content sync, and an api entry without an apiCollection() under its key fails the build, including a key registered with another loader. Both messages name the Nimbus config and src/content.config.ts, and nimbus-docs check reports the same mismatches without building.

    apiCollection(options) and @cloudflare/nimbus-docs/config are unchanged, and sites built by earlier versions of the recipe keep building with no changes. Upgrade note: in astro dev, that shape silently ignores edits to the api entry in nimbus.config.ts until a manual restart. To pick up edits automatically, move the Nimbus config back into astro.config.ts, delete the lookup in src/content.config.ts, and register the collection with apiCollection(). nimbus-docs upgrade lists these steps.

    Also fixes astro dev after an astro.config.* edit, for every site: collections are re-synced when Astro restarts the dev server, so docs pages keep their partial headings and Markdown routes and llms.txt keep working, instead of losing prepared data until a manual restart. Spec edits keep re-indexing API pages after that restart.

  • #165 05efc7a Thanks @MohamedH1998! - Keep more of the OpenAPI document in API reference pages and their Markdown versions:

    • Request body required and description. ApiOperationPage gains bodyRequired, bodyDescription, and bodyDescriptionHtml, read from the operation’s Request Body Object. Each is present only when the spec states it.
    • Every response media type. The primary media type is chosen exactly as before and is now exposed as ApiResponseView.mediaType. Each other media type is listed in ApiResponseView.additionalMedia (ApiResponseMediaView: mediaType, anchor, fields, and optional truncated, union, and example), with fields citable at <operation>.response.<status>.<media-token>.<field>. The build no longer warns that it renders only the first media type. A media type whose coordinate token would clash, with a sibling media type (such as application/vnd.a+json beside application/vnd.a-json) or with a field of the primary body (a property named text-csv beside text/csv), no longer fails the build, for responses or request bodies: it gets a short hash suffix instead. Media types that don’t clash keep their existing coordinates.
    • Readable union branch labels. A oneOf/anyOf branch without a $ref is labeled by its title, then by the type of its folded allOf, then by the type of its enum/const values, then object when it has properties, and otherwise Option N. Branches are never labeled unknown. Field types are unchanged.

    The generated Markdown shows the body’s required flag and description, one labeled body per response media type, and the new branch labels. All changes are additive, and apiSchemaVersion stays 1. Pages whose spec uses none of these constructs render the same HTML and Markdown as before.

  • #164 b8f4d05 Thanks @MohamedH1998! - Return each page’s URLs from the page helpers, build OG cards from one path function, and reduce the llms.txt routes to one factory call each.

    • getDocsPage, getCollectionPage, getDocsPageProps, and getCollectionPageProps now return markdownUrl, sourceUrl, and ogImageUrl alongside entry, Content, and headings. IndexedEntry gains ogImageUrl. All three are site-relative with no base path and come from the same function, so a page route no longer builds them by hand:

      const { entry, Content, headings, markdownUrl, ogImageUrl } = page;
const socialImage = entry.data.socialImage ?? ogImageUrl;

    • getOgImagePages() from @cloudflare/nimbus-docs/runtime returns the pages map for astro-og-canvas’s OGImageRoute, one entry per indexed page, keyed so each card is written at the page’s ogImageUrl. ogImageUrl is /og/<page>.png, derived from the page’s route, the same rule the api-reference recipe uses. This fixes broken OG cards: collection and version root pages, such as /blog/, linked to /og/blog/index.png while the card was written at /og/blog.png, and IDs containing a dot, such as v1.2/guide or the webhook payment.succeeded, had their card name cut at the last dot, so several pages shared one card. noindex pages linked to /og/<id>.png, but the old OG route skipped them and never wrote that card. Root pages, dotted IDs, and noindex pages now link to cards that exist.

    • llmsRoute(), llmsFullRoute(), and llmsSectionRoute() from @cloudflare/nimbus-docs/agent-endpoints return the { GET } behind src/pages/llms.txt.ts and llms-full.txt.ts, and the { GET, getStaticPaths } behind src/pages/[section]/llms.txt.ts. Each GET returns 404 for a missing or unknown index and, on request, a 500 without details when the index can’t be read, as the starter’s routes did:

      // src/pages/[section]/llms.txt.ts
import { llmsSectionRoute } from "@cloudflare/nimbus-docs/agent-endpoints";

export const prerender = true;
export const { GET, getStaticPaths } = llmsSectionRoute();

    • The build now warns about every baked Markdown page and every llms.txt index that no prerendered route generated, and names the route that serves it. This catches a shared Markdown route that re-exports markdownRoute() from another module and is rendered on request. Sites that serve these pages on request on purpose can ignore the warning.

    Hand-built URLs, existing OG routes, and existing llms.txt routes keep building with unchanged output. The page-urls-and-llms-routes upgrade entry lists the lines each route can drop.

  • #161 b45ca22 Thanks @MohamedH1998! - Serve the Markdown and source versions of every collection from two route files. markdownRoute() and markdownSourceRoute() from @cloudflare/nimbus-docs/agent-endpoints return { GET, getStaticPaths }:

    // src/pages/[...slug]/index.md.ts
import { markdownRoute } from "@cloudflare/nimbus-docs/agent-endpoints";

export const prerender = true;
export const { GET, getStaticPaths } = markdownRoute();
    • One shared route serves every collection’s /<page>/index.md, including docs versions and API reference pages. markdownSourceRoute() serves /<page>/index.mdx for every authored page. Collections added later need no new route files.
    • A more specific route file, such as src/pages/changelog/[...slug]/index.md.ts, takes over its collection. The shared route skips every URL that route matches, so Astro reports no route conflicts. If the more specific route doesn’t generate every page it matches, the build warns and names the missing paths, or fails when prerenderConflictBehavior is "error".
    • The shared routes must be prerendered. The build fails if a route using markdownRoute() or markdownSourceRoute() is rendered on request.
    • API pages now have baked Markdown assets, so getMarkdownStaticPaths({ collection: "<api>" }) returns their entries. Hidden API versions are excluded, like hidden docs versions.

    Existing per-collection routes keep working and need no change. Sites that delete the api-reference recipe’s src/pages/<api>/[...slug]/index.md.ts no longer publish Markdown for hidden API versions. The shared-markdown-routes upgrade entry explains how to remove unmodified per-collection routes.

Patch Changes

  • #164 c26b52b Thanks @MohamedH1998! - Support dotted version slugs such as v1.2. Links to a dotted version root now keep their trailing slash (/v1.2/, not /v1.2) in the sidebar, breadcrumbs, version picker, alternate links, and IndexedEntry.url; before, the last segment was read as a file extension. src/content.config.ts keys such as "docs-v1.2" are now recognized, so Nimbus no longer warns that collections can’t be identified statically and keeps its collection checks on.

  • #167 2223c45 Thanks @MohamedH1998! - Keep builds running when an upgrade range contains only optional guidance, while surfacing those entries in the build log and upgrade commands.

  • #166 9eef696 Thanks @MohamedH1998! - When GitHub refuses the template lookup (or rejects the token) in nimbus-docs outdated or diff, the error now explains how to fix it: set GIGET_AUTH to a GitHub token, or skip the lookup with --to or --template-dir. It also says when GitHub’s rate limit resets, or quotes GitHub’s reason. The CLI help now mentions GIGET_AUTH.

create-nimbus-docs 0.7.7

Patch Changes

  • #165 05efc7a Thanks @MohamedH1998! - The API reference components show whether a request body is required, and its description, beside the request body heading. A response with several media types shows one body per media type, each labeled with its type and with its own example, in the same stacked layout as additional request bodies. ApiFieldList accepts optional required and descriptionHtml props for this.

  • #164 b8f4d05 Thanks @MohamedH1998! - The starter’s page route takes markdownUrl and ogImageUrl from getDocsPage(), its OG route builds cards from getOgImagePages(), and its three llms.txt routes call llmsRoute(), llmsFullRoute(), and llmsSectionRoute(). src/utils/agent-endpoint-response.ts is removed. Built output is unchanged.

  • #161 b45ca22 Thanks @MohamedH1998! - The starter’s src/pages/[...slug]/index.md.ts and index.mdx.ts routes now use markdownRoute() and markdownSourceRoute(), so they serve the Markdown and source versions of every collection. Generated files are unchanged.

  • Updated dependencies [982a47d, c26b52b, 05efc7a, 2223c45, 9eef696, b8f4d05, b45ca22]:

    • @cloudflare/nimbus-docs@0.15.0

nimbus-docs 0.14.2

Patch Changes

  • #160 08b963b Thanks @MohamedH1998! - Prose api.ref: citations now resolve correctly in HTML output:

    • They include the site’s base path. On a site with base: "/docs", [change status](api.ref:api:changeWidgetStatus) now links to /docs/api/... instead of /api/..., matching the Markdown alternate and llms-full.txt.
    • Citations in .md pages now resolve. Previously they rendered as raw api.ref: links; only .mdx pages were resolved.
    • Citations resolve when the project directory is reached through a symlink.

  • #157 cde0751 Thanks @MohamedH1998! - Render authored OpenAPI request examples as selectable examples in API reference pages and generated Markdown.

  • #158 9f024b0 Thanks @MohamedH1998! - Reduce static API reference build memory by storing lightweight collection entries and projecting complete pages during prerendering. Server output continues to use prepared entries so requests do not parse OpenAPI specifications. Keep build-only Markdown parsing out of generated server bundles.

create-nimbus-docs 0.7.6

Patch Changes

  • #157 cde0751 Thanks @MohamedH1998! - Render authored OpenAPI request examples as selectable examples in API reference pages and generated Markdown.

  • #154 f9aecd8 Thanks @sansynx! - Keep footnote targets visible below the sticky header when following note and return links.

  • Updated dependencies [08b963b, cde0751, 9f024b0]:

    • @cloudflare/nimbus-docs@0.14.2

nimbus-docs 0.14.1

Patch Changes

  • #151 22ae398 Thanks @MohamedH1998! - Fix native admonition parsing after astral Unicode characters.

  • #148 dc9e3ff Thanks @sansynx! - Run the Pagefind indexing step on Windows instead of failing to launch the project command shim.

create-nimbus-docs 0.7.5

Patch Changes

  • Updated dependencies [22ae398, dc9e3ff]:
    • @cloudflare/nimbus-docs@0.14.1

Type to search…

↑↓ navigate↵ selectEsc close