Changelog, page 4

Aug 20, 2026

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.

Aug 11, 2026

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.

Aug 11, 2026

create-nimbus-docs 0.6.5

Patch Changes

• #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.

• #70 b9620bc Thanks @MohamedH1998! - Fix search dialog results not scrolling. The results wrapper now lays out as a flex column, so the results list gets a bounded height and its overflow-y-auto engages — long result sets scroll within the dialog instead of being clipped, while the search input stays in view above the scroll region.

• #71 4d6815f Thanks @MohamedH1998! - Make pkg.pr.new preview builds scaffold from bundled PR templates and pin generated projects to the matching @cloudflare/nimbus-docs preview.

  Generated starters are now pinned to the verified Astro 7.0.x line while the upstream Astro 7.1.x static build regression is open.

Aug 4, 2026

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.

Aug 4, 2026

create-nimbus-docs 0.6.4

Patch Changes

• #64 d551fa2 Thanks @MohamedH1998! - Stop shipping the .nimbus/ build directory into scaffolded projects

  .nimbus/ holds build artifacts materialized by astro build (routes.json, lint.json). It had leaked into the starter source and was being copied into new projects, so a freshly scaffolded app carried stale route and lint truth from the template rather than its own. .nimbus is now excluded by both the template-copy script and the runtime scaffolder, and removed from the starter source; a new project starts with no build artifacts and generates its own on first build.

• #64 e1e4e8d Thanks @MohamedH1998! - Point the scaffolded AGENT.md at nimbus-docs check

  The generated AGENT.md now documents the one-command model: a “Check it builds” row in the actions table (env + structure + authoring + types), and an “Audit this site” section that leads with nimbus-docs check --json before the manual walk of what check doesn’t cover yet (route-file existence, registry hygiene, AI surface, post-build search, Cloudflare config).

  It teaches an agent the honest result contract: the primary signals are status (passed|failed|partial) and readiness (buildable|blocked|unknown), with ok kept only for back-compat; a check that couldn’t be evaluated yet (e.g. types before a build) is a note under scopes[].notes[] — never a finding, never a fix — so the fix loop terminates on status !== "failed" && summary.fixable === 0 rather than spinning on a coverage gap it cannot repair.

Jul 24, 2026

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.

Jul 24, 2026

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.

Jul 24, 2026

create-nimbus-docs 0.6.3

Patch Changes

• #55 a986d61 Thanks @MohamedH1998! - The scaffolded starter’s header now matches the Nimbus site. The mobile menu (hamburger) button moved from the left of the header to the right, alongside the theme toggle. The search trigger stays reachable on mobile: it previously used hidden sm:flex and disappeared entirely below the sm breakpoint, leaving phones with no way to search — it now renders as a compact magnifying-glass icon button on small screens and expands to the full “Search ⌘K” control from sm up (the ⌘K hint is hidden on mobile).

• #55 6881e4e Thanks @MohamedH1998! - Markdown tables in the scaffolded starter now round their outer corner cells to match the table’s 0.75rem border-radius. Because the table uses border-collapse: separate, the corner cell backgrounds — most visibly the muted <thead> fill — previously kept square corners that poked past the rounded table border. The first/last <th> in the header and the first/last <td> in the last body row now carry the matching border-top-left/border-top-right/border-bottom-left/border-bottom-right radius, so the fill clips cleanly to the border. Scoped to :not([class]) authored markdown tables, so component-owned tables are untouched.

Jul 23, 2026

nimbus-docs 0.8.0

Minor Changes

• #42 8e4e210 Thanks @MohamedH1998! - Add the ownership + upgrade loop to the nimbus-docs CLI:

  • nimbus-docs init — reconstruct a nimbus.json for a project that lacks one (scaffolded before this record existed, an existing Astro site adopting Nimbus, or a deleted record), matching installed components against the registry and marking what it can’t recover.
  • nimbus-docs outdated — a read-only check across both tiers: starter files behind their templates-v* tag (which git diff can’t show) and registry components whose recorded bytes differ from the registry.
  • nimbus-docs diff [file] / diff --apply <file> — review upstream/your changes to starter files, and pull a clean upstream change per file (never a merge).
  • nimbus-docs add <slug> --overwrite — re-install a component over your copy (review with git diff). add also records each install in nimbus.json.

  Also adds a getRouteFlags layout-flag helper and a CI guard for the registry tier invariants.

  Migration — add --yes no longer overwrites files you own. It now assents to prompts (dependency installs, etc.) but keeps existing files on conflict, so a bare -y in CI never clobbers your code. Use --overwrite to replace files.

  # before — --yes overwrote conflicting files
  nimbus-docs add card --yes
  
  # after — replace files explicitly
  nimbus-docs add card --overwrite

• #34 73bbecf Thanks @mvvmm! - nimbus/internal-link and nimbus/image-ref now match their ignore: string[] option against full glob syntax (**, *, {a,b}, extglobs, …) via picomatch, not just an exact match or a prefix immediately followed by /**. In particular, a leading any-depth wildcard like **/llms.txt is now supported — the previous hand-rolled matcher had no way to express that.

  Existing ignore lists using only exact paths or prefix/** patterns keep working unchanged.

Jul 23, 2026

create-nimbus-docs 0.6.2

Patch Changes

• #42 8e4e210 Thanks @MohamedH1998! - Scaffolded projects now include a committed nimbus.json — a CLI-managed record of the create-nimbus-docs version, the templates-v* tag, the install root, and (as you nimbus-docs add) each installed component’s provenance. Starter components also get an API-consistency pass: type→variant on Banner/Callout, VersionPicker→VersionSwitcher, hydration moved out of inline scripts into .client.ts files via the mount() primitive, and a single getRouteFlags layout-flag helper. The scaffolded AGENT.md now documents the outdated / diff / add --overwrite upgrade flow.

• #34 b8a1235 Thanks @mvvmm! - Bump for the @cloudflare/nimbus-docs minor in this release (full glob support for ignore in internal-link/image-ref) — no starter-source changes.