Changelog, page 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.

nimbus-docs 0.14.0

Minor Changes

• #129 3fd7d15 Thanks @MohamedH1998! - Add a versioned breaking-change manifest, explicit reviewed upgrade baselines, agent-readable migration plans, shared check and outdated diagnostics, safe starter drift updates, starter agent upgrade guidance, and automatic migration guidance during Astro configuration.

• #142 5343933 Thanks @MohamedH1998! - Breaking: API coordinate manifests now use the compact v2 format exclusively. The existing getCoordinatesManifest() helper emits it by default; the endpoint, citation syntax, page URLs and anchors are unchanged. Repeated page URLs are stored once per namespace in a single JSON file. There is no additional helper or setting.

  Upgrade publishers and consuming sites together, rebuild publishers, and refresh checked-in manifests before rebuilding consumers. Old readers cannot consume v2, and new readers no longer consume v1. Stage both sides before switching live sites if uninterrupted citations are required. Local v1 references fail with rebuild guidance; remote v1 references warn and are skipped.

  Custom CoordinatesManifest readers must use collection pages and versions page groups instead of the old flat entries. Each group has a literal url and coordinate-keyed fragments: null means no fragment, 0 means the coordinate itself, and a string is the exact fragment. Do not relabel old JSON as v2.

  The linked upgrade-manifest entry includes rollout, verification and rollback guidance. This changes citation transport, not Astro’s content store or SSR behavior.

• #139 ea8cd46 Thanks @MohamedH1998! - Render MDX admonitions with Sätteri’s native directive parser, preserving nested content, code examples, plain titles, aliases, and scoped opt-outs. Use markdown.mdastPlugins and markdown.hastPlugins for native extensions. Explicit incompatible processors must disable Nimbus admonitions, while Astro MDX options continue to pass through unchanged. Native admonitions now apply to .mdx only; review existing admonition directives in .md files. Astro 7.2.6 or newer is required.

Patch Changes

• #122 4b51ebb Thanks @MohamedH1998! - Allow user-owned Astro pages and scaffolded Markdown and llms.txt endpoints to use native rendering semantics while retaining entrypoint-aware checks for active Nimbus contracts and composing with unrelated integration routes. These dynamic endpoints now resolve their payloads when rendered on request. Endpoint helpers now live at @cloudflare/nimbus-docs/agent-endpoints; the existing @cloudflare/nimbus-docs/publication entrypoint remains supported. Sub-path sitemaps now list the deployment root once.

• #138 3f7c16a Thanks @MohamedH1998! - Preserve authored root-relative links and unrelated source across Markdown and MDX, including HTML containers, fenced examples, Unicode, and CRLF. Keep plain Markdown unchanged when generating Markdown and agent endpoint output.

• #137 728e753 Thanks @MohamedH1998! - Update generated projects to Astro 7.2.8 and align the Node adapter with Astro’s updated runtime API.

nimbus-docs 0.13.1

Patch Changes

• #110 e6fb2b1 Thanks @sansynx! - Reject registry install paths that resolve outside src through symbolic links.

• #109 f4d0d78 Thanks @sansynx! - Preserve casing in static page routes during duplicate-route checks.

• #119 bd179bb Thanks @MohamedH1998! - Index API response coordinates for direct citations, and keep scaffold progress readable in non-interactive terminals. Emit canonical trailing slashes for API navigation links.

nimbus-docs 0.13.0

Minor Changes

• #114 3c0d794 Thanks @MohamedH1998! - Generate deterministic Markdown versions for every public page, prepared MDX source versions for authored pages, llms.txt indexes, llms-full.txt, and merged partial headings at build time. Request-rendered pages now consume compact prepared heading data, and custom component transforms and partial resolvers are configured through markdown.componentMap and markdown.partialResolver. Worker bundles no longer include partial-expansion parsers. Calls to renderEntryAsMarkdown or getEntryMarkdown that still pass <Render> partials now fail instead of attempting runtime expansion; migrate custom Markdown routes to the prepared helpers exported by @cloudflare/nimbus-docs/build.

  Rename prepared publication APIs without compatibility aliases: TwinSurface becomes PreparedMarkdownSurface, PreparedTwin* becomes PreparedMarkdown*, PreparedCorpus* becomes PreparedLlms*, getPreparedTwin* becomes getPreparedMarkdown*, getPreparedCorpus* becomes getPreparedLlms*, and renderCorpusMarkdown becomes renderLlmsFullMarkdown. Move integration customization from twins.componentMap and twins.partialResolver to markdown.componentMap and markdown.partialResolver.

  Keep framework assets, metadata, starter navigation, and generated API links inside Astro’s configured deployment base path. Replace the removed withBaseRoute runtime export with withBase; site-relative inputs to withBase must be logical, unbased paths.

  Keep generated .nimbus build data out of source control, deduplicate sitemap roots on subpath deployments, and advertise prepared MDX source responses as text/mdx consistently across static and request rendering.

nimbus-docs 0.12.0

Minor Changes

• #93 43c161a Thanks @MohamedH1998! - Add first-party OpenAPI reference support to Nimbus.

  • Configure local or inline OpenAPI specs as routed, version-aware collections with operations, schemas, tags, webhooks, generated samples, and every declared request-body media type.
  • Install an editable api-layout UI that shares Nimbus’s docs shell, navigation, breadcrumbs, banners, mobile behavior, and deep-linkable field and code-sample controls. The copied ApiFieldList field iterator is explicitly typed so the scaffolded UI type-checks cleanly under a consumer’s strict TypeScript.
  • Publish per-page Markdown, agent indexes, corpus entries, coordinate manifests, and api.ref: citations across local and cross-site documentation.
  • Harden generated-consumer delivery with exact registry dependencies, working pnpm installs from scaffold roots, and base-aware canonical, Markdown, sitemap, and agent URLs through the new public withBase helper.
  • Control how operation pages are addressed, and stay resilient to messy specs. By default, operations that lack a usable operationId no longer abort the build — they warn and fall back to a path-derived coordinate, so real-world specs (e.g. Cloudflare’s brand-protection operations) build; set api[].requireOperationId: true on specs you own to keep that fatal, while route-hostile paths and coordinate collisions stay fatal regardless. For readable, path-derived URLs, opt into the resource-action-v1 route convention: set api[].routes: { convention: "resource-action-v1" } (per version in a family) to derive slugs like charges/list from an operation’s method and path, decoupled from operationId so route-hostile identifiers no longer poison URLs. Trim shared bases with stripPathPrefixes (e.g. ["/v1"]), pin individual pages with an operations (operationId → slug) map, and inspect how each slug resolved (override / derived / fallback) via the new getApiRouteProvenance export. Derivation collisions, reserved-route segments, unused overrides, cross-version slug drift, and unknown config keys (e.g. a stripPrefixes typo for stripPathPrefixes) are reported with pointed messages; the default (no routes) keeps the legacy operationId slugs unchanged.

• #104 79d6430 Thanks @MohamedH1998! - Add server-output support and the @cloudflare/nimbus-docs/adapters export.

  Nimbus can now target on-request (server) output in addition to static. A new @cloudflare/nimbus-docs/adapters public export ships the adapter recipes plus the shared astro.config and wrangler.jsonc emitters, and two new CLI verbs opt an existing site in: nimbus-docs add server-output --adapter <vercel|node|netlify|cloudflare> (alias nimbus-docs add adapter-<id>). The installer rewrites astro.config at the // nimbus:adapter marker and, for Cloudflare, creates a server wrangler.jsonc or replaces an exact Nimbus static config. Cloudflare installs add request rendering when the active Nimbus config has no explicit rendering policy; explicit or ambiguous policies are preserved and receive an agent-ready handoff. Adapter dependencies are saved at their exact resolved versions so subsequent runs accept the installed declaration. Custom and alternate Wrangler configs are preserved with manual adaptation instructions.

  Withdraw the gated config option because it did not hold as a confidentiality boundary. Existing gated config now fails with a migration error; to keep a page out of the build, move the page out of a routed content collection.

  Fix env preflight precedence and parsing to match Vite, including empty shell overrides, last-wins .env* files, and inline dotenv comments. Adapter dependency validation now resolves pnpm catalog declarations, and compatibility warnings reflect the versions installed by the command.

  Fix NimbusHead URLs for sub-path deployments by applying Astro’s configured base to sitemap, LLM index, social image, JSON-LD, canonical, and version-alternate URLs. Root deployments and already-based paths are unchanged.

  Keep registry component render counters compatible with adapter-defined Astro.locals types, including Cloudflare server output.

• #104 862df4a Thanks @MohamedH1998! - Add Cloudflare request rendering for canonical content collections.

  Nimbus now supports collection-level build and request rendering policies with validated defaults and per-collection overrides. Request-rendered prose and API routes use response-aware page helpers, prepared API models, request-safe partial headings, 404 responses, and build-derived syntax-highlighting assets without shipping source OpenAPI specs to Workers. Cloudflare server scaffolds enable request rendering by default, and generated pnpm configuration installs Satteri’s WASI fallback alongside the current architecture.

  Preserve sitemap, Pagefind, Markdown, and agent-index discovery for request-rendered routes. Pin the tested sitemap integration, clean up synthetic Pagefind staging files transactionally, and generate cross-collection Open Graph images in new starters.

Patch Changes

• #99 2965d9f Thanks @MohamedH1998! - - Honor noindex: true on machine discovery surfaces. noindex pages now drop out of /llms.txt, per-section llms.txt, and the /llms-full.txt corpus (matching on-site search, which already excluded them) while staying directly addressable and navigable. A single exported isDiscoverable predicate defines the contract for custom index/corpus routes.
  • Pin @vercel/detect-agent to 1.2.3, the last release published with npm provenance. Versions 1.2.4/1.2.5 dropped provenance, tripping pnpm’s ERR_PNPM_TRUST_DOWNGRADE and blocking lockfile updates. Pinning holds at the attested artifact until upstream restores provenance.
  • Fix navigation for pages under CJK (percent-encoded) paths. Route matching now decodes percent-encoded request paths (toRouteKey), so active sidebar state, breadcrumbs, and prev/next resolve correctly instead of falling back to a URL-encoded trail; the breadcrumb URL fallback also decodes segment labels.

nimbus-docs 0.11.0

Minor Changes

• #86 b4b0dc3 Thanks @MohamedH1998! - makeDisclosure now marks closed content inert so collapsed regions leave the tab order, keeping keyboard focus out of hidden disclosure panels. Add a manageInert option (default true) to opt out for consumers that manage their own focus.

• #90 74702e0 Thanks @mvvmm! - getDocsStaticPaths and getCollectionStaticPaths now include a cacheKey (derived from the entry’s digest) on each returned path. This enables Astro’s experimental incremental build cache to skip re-rendering unchanged pages. No-op when experimental.incrementalBuild is not enabled in astro.config.ts.

Patch Changes

• #95 79a8448 Thanks @mvvmm! - Bump nanoid to 3.3.18 to resolve GHSA-2v37-7h3g-55p8 (CVE-2026-67213): custom generators can loop indefinitely when size is zero.

nimbus-docs 0.10.0

Minor Changes

• #71 e5d74f9 Thanks @MohamedH1998! - Enable MDX optimization by default to reduce large-site build memory usage. Sites can opt out with mdx: { optimize: false }.

  Verified the generated starter with optimization on and with mdx: { optimize: false } forced; the rendered HTML is structurally equivalent for element names, attributes, and non-whitespace text. Render parity is semantic and structural rather than byte-identical: raw bytes differ due to serializer escaping and inter-block whitespace, but the rendered document is lossless.

  Spot-checked the starter components page, which includes JSX tags in prose, inline code with <...>, quoted code, and package names. The optimized and opt-out renders preserve those special-character text probes and match structurally.

  Constrain the supported Astro peer range to >=7.0.0 <7.1.0 || >=7.2.0 <8.0.0: the 7.1.x line is excluded while its static-build regression is open upstream, but 7.2.x is admitted (verified against a sub-path build). Generated templates and the dev pin stay on the verified 7.0.x line.

• #76 acfac20 Thanks @mvvmm! - Replace astro-icon with a built-in icon system. This is a breaking change for any project using astro-icon directly.

  Why: astro-icon stamped a generated lastModified timestamp into its virtual module on every build, invalidating thousands of cached pages in Astro’s incremental build cache. The package is unmaintained so an upstream fix isn’t coming.

  What’s new: Nimbus now provides virtual:nimbus/icons (a Vite plugin) and @cloudflare/nimbus-docs/components/Icon.astro. The plugin auto-detects installed @iconify-json/* packages and loads local SVGs from src/icons/. The component API is compatible with astro-icon (name, size, width, height, is:inline, title, desc, and all <svg> attributes). SVG bodies are passed through replaceIDs so internal IDs (clipPath, mask, gradient defs) are unique per render — preventing collisions when the same icon appears more than once on a page.

  Breaking changes:

  • Remove astro-icon from your package.json and astro.config.ts
  • Replace import { Icon } from "astro-icon/components" with import Icon from "@cloudflare/nimbus-docs/components/Icon.astro"
  • SVG output structure changed: SVGs are always inlined; the previous <symbol>/<use> pattern produced duplicate DOM IDs when the same icon was used more than once on a page, so it has been removed. Any CSS or JS targeting symbol or use elements will need updating.

  Migration:

  - import { Icon } from "astro-icon/components";
  + import Icon from "@cloudflare/nimbus-docs/components/Icon.astro";

  Starter templates updated: removed astro-icon dependency and icon() integration from astro.config.ts; all component imports updated to the new path.

Patch Changes

• #77 1c49268 Thanks @MohamedH1998! - Fix NimbusHead emitting base-less SEO URLs on sub-path deployments (e.g. base: '/docs').

  new URL(path, Astro.site) resolves against the origin only and drops the configured base, so the rel=sitemap link, the LLM-index rel=alternate, og:image/twitter:image, the JSON-LD isPartOf.url, the versioned canonical, and the cross-version rel=alternate all pointed at the origin root and 404’d under a sub-path. Every internal path handed to new URL(..., Astro.site) is now base-prefixed via a withBase helper, matching the existing BASE_URL handling for the favicon and Shiki stylesheet.

  Root deployments (base: '/') are unaffected: the helper is a no-op when no base is configured, and already-based paths pass through unchanged (idempotent).

• #80 ec71a7b Thanks @MohamedH1998! - Fix syntax-highlighted code rendering uncoloured in dev on sites with a non-root base (e.g. base: "/docs"). The dev middleware that serves _nimbus/shiki.css compared the request path exactly against the based asset path, but Vite strips base from req.url at a non-root base, so the request 404’d and tokens fell back to their inherited colour. It now matches by suffix, serving the stylesheet regardless of how Vite presents base. Production was unaffected — the stylesheet is written statically at build time.

nimbus-docs 0.9.0

Minor Changes

• #64 e1e4e8d Thanks @MohamedH1998! - Add nimbus-docs check — a build-free preflight that reports readiness honestly

  One command a human, CI, or agent runs to catch setup, structural, authoring, and type problems before a build. It runs four categories — environment (Node floor, config locatable, site not a placeholder, pagefind, wrangler), structure (config Zod, duplicate routes, MDX component resolution — the same validators the build gates on), authoring (the shipped lint rules), and types (a build-free type-check) — and normalizes every result into one envelope.

  The types category type-checks your TypeScript with your project’s own tsc, build-free — no astro build, no astro sync, nothing spawned (your TypeScript is resolved from your project, never bundled into the CLI). Astro transpiles rather than type-checks, so a type error never fails the build on its own; catching it in the preflight is the point. Because tsc can’t parse .astro SFCs, their internals and prop types are out of scope (that needs astro check); an injected ambient declare module "*.astro" keeps .ts files that import .astro components from being false-flagged.

  The report separates two axes that a naive error count fuses: buildability vs. correctness, and evaluated vs. not-evaluated. --json carries three top-level signals:

  • status (passed | failed | partial) — the whole-run verdict across every scope that ran.
  • readiness (buildable | blocked | unknown) — derived from env + structure only: does the project clear Nimbus’ buildability checks? A type error is status: failed but readiness: buildable (the site still builds — Astro strips types); a placeholder site is blocked.
  • ok — kept for back-compat, still exactly errors === 0.

  Exit is 1 only when status === "failed" (ok === false); partial and readiness never move it. Usage errors are 2.

  Coverage is a first-class channel, not a fake warning. A sub-check that can’t run yet — opt-in authoring rules or link-checking before astro build materializes .nimbus/lint.json / .nimbus/routes.json, or the type-check before .astro/types.d.ts exists — is reported as a note under scopes[].notes[{ code, reason, requiresBuild?, requiresInput? }], counted in summary.notes. A note is never a finding, never carries a fix, and never affects the exit code; it resolves by making the missing thing exist (a build), not by --fix. A run that skipped types or authoring rules therefore never declares itself build-ready on an unverified scope. The headline is earned: “Buildable” on a scaffold whose correctness scopes are still notes, “Ready” only when every scope that ran evaluated clean with zero notes.

  • --json emits { ok, status, readiness, summary{errors,warnings,notes,fixable,durationMs}, scopes[{scope,status,reason?,notes[]}], findings[{scope,code,severity,file,line,message,fixable,fix}] }. An agent’s fix loop terminates on status !== "failed" && summary.fixable === 0 — a partial run with nothing left to fix is a stop (optionally build, then re-check), not a --fix retry.
  • --fix applies safe fixes (installs, config rewrites via a static parse of astro.config.ts), prompting on a TTY for values it can’t invent (e.g. the production site URL) and skipping them headless.
  • --env / --structure / --lint / --types run a single category.
  • init now ends with the env readiness pass — using the same scope-status vocabulary — so a fresh scaffold hears about a placeholder site at setup time.

  lint is preserved as a first-class command with its own “zero .mdx → exit 1” guard; check --lint runs the same rules inside the preflight envelope. (Unlike lint, a config-only project with no .mdx is not an error for check.)

  Config validation for site is now stricter: it must be an absolute http(s):// URL with a host. Previously a value missing the // (e.g. https:example.com) slipped through new URL() and shipped a broken canonical origin; it is now rejected both build-free by check and at build time by the config gate.

nimbus-docs 0.8.2

Patch Changes

• #59 01a5d23 Thanks @MohamedH1998! - Fix overview-leaf reordering a flat top-level sidebar per page

  In indexDisplay: "overview-leaf" mode, the section-root pin relabelled and moved any top-level link whose slug matched the current section — including standalone top-level pages with no content beneath them. On a flat top-level of single pages, that pulled the current page to the front and renamed it “Overview” on every page. Pinning now requires the section to actually have content under it, so standalone pages stay put and keep their label.

nimbus-docs 0.8.1

Patch Changes

• #55 a590ebd Thanks @MohamedH1998! - CLI hints now print a runnable, scoped invocation instead of the bare nimbus-docs binary. Error messages, install hints, and --help reference pnpm dlx @cloudflare/nimbus-docs … (matched to your package manager — npx / yarn dlx / bunx), so a first-run dlx/npx user can copy-paste them, and they never resolve the unrelated legacy unscoped nimbus-docs package on npm. For example, an unknown slug now suggests pnpm dlx @cloudflare/nimbus-docs list rather than nimbus-docs list. Once @cloudflare/nimbus-docs is a project dependency you can still call the nimbus-docs bin directly (via pnpm exec or an npm script) — --help documents both. The “framework is behind” nudge from outdated now suggests your package manager’s update command instead of a hardcoded npm update.