CHANGELOG.md

@cloudflare/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.

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.

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.

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.

0.6.1

Patch Changes

• #32 a6491c8 Thanks @MohamedH1998! - Fix a batch of UI stress-sweep defects in the starter components:

  • TOC scroll-spy no longer desyncs when a heading slugs to an empty id (e.g. an emoji-only ## 🎉). The active-heading index now stays aligned with the full link/rail set instead of a resolvable-only subset, so every section below an unresolvable heading highlights correctly.
  • Mobile sidebar hamburger survives client-side navigation — the toggle re-binds on astro:page-load and tears down on astro:before-swap (via mount()), fixing a dead button after the first view transition, with the scroll lock balanced on a mid-open swap.
  • Dialog content taller than the cap now scrolls inside the panel (overflow-y-auto) so the close button stays reachable.
  • Banner long unbroken strings (including the framework deprecation banner's version URL) wrap instead of overflowing.
  • PackageManagers blocks with identical props on one page now get unique, incremental-build-stable DOM ids (per-page counter), fixing duplicate id/aria-controls.
  • Dev-only warnings: <Steps> around a bullet list, and duplicate labels within a <Tabs syncKey> group.

0.6.0

Minor Changes

• #27 1ebfb6c Thanks @MohamedH1998! - Align the sidebar + add a mobile "On this page" TOC matching cloudflare-docs, and tighten the docs layout's mobile and horizontal-overflow handling.

  • Sidebar + TOC: the sidebar filter gains a press / to focus kbd hint and a placeholder prop; sidebar groups render an optional leading icon (from sidebar.group.icon); and a sticky native-<select> "On this page" TOC now appears under the page title on viewports below xl, where the desktop TOC rail hides.
  • Mobile sidebar drawer: the drawer no longer dims or blurs the page — it slides in over a transparent overlay so the page copy stays readable, with a hairline edge instead of a shadow. Both the drawer panel and the desktop sidebar now paint their own background and contain overscroll, fixing a "no background" flash on fast/momentum scroll.
  • Tabs: a tab strip wider than its column now scrolls horizontally (scrollbar hidden) instead of leaking past the page width, and the active tab is scrolled into view on activate/restore.
  • Prose: long unbroken tokens (URLs, hashes) wrap within the content column via overflow-wrap: break-word instead of overflowing the page; code blocks and wide tables keep their own scroll handling.

0.5.2

Patch Changes

• #24 52d5a0c Thanks @MohamedH1998! - Fix scaffolded starter behavior across client-side navigations and add a 404 page.

  • Re-run component initializers on astro:page-load so interactive components (code groups, dialogs, popovers, file trees, search) keep working after ClientRouter/view-transition navigations.
  • Scope the search dialog's global key handler to a module variable instead of an <html> attribute, preventing a duplicate Cmd+K handler from stacking on each navigation.
  • Mark inline SVG icons with is:inline so they render reliably.
  • Ship a default 404.astro page in the starter.

0.5.1

Patch Changes

• #22 7ec9715 Thanks @MohamedH1998! - Republish with npm provenance attestations. Supersedes 0.6.0 / 0.5.0, which published without provenance and before the repo was public.

0.5.0

Minor Changes

• #20 fde68eb Thanks @MohamedH1998! - Rename to the @cloudflare npm scope

  nimbus-docs → @cloudflare/nimbus-docs and create-nimbus-docs → @cloudflare/create-nimbus-docs. The unscoped packages are deprecated and receive no further releases.

  Migration:

  • Framework: pnpm remove nimbus-docs && pnpm add @cloudflare/nimbus-docs, then update imports — from "nimbus-docs" → from "@cloudflare/nimbus-docs" (every subpath follows: /content, /schemas, /types, /client, /markdown, /react, /lib/pkgm, /components/NimbusHead.astro). The nimbus-docs CLI bin name is unchanged.
  • Scaffolder: pnpm create nimbus-docs → pnpm create @cloudflare/nimbus-docs.

  No API, config, schema, or runtime behavior change — only the package names and import paths.

0.4.1

Patch Changes

• #16 479349b Thanks @MohamedH1998! - Templates now pin nimbus-docs 0.5.0

  Scaffolds pin nimbus-docs at the minor they were generated against, so this CLI re-releases to ship templates on 0.5.0 — which drops the built-in incremental-build cache (the incrementalBuilds option, the partialResolver hook, and nimbus-docs clean). New scaffolds use a plain astro build; Astro 7's native incremental building applies without any Nimbus opt-in.

0.4.0

Minor Changes

• #13 456ca74 Thanks @MohamedH1998! - Move to Astro 7

  nimbus-docs now peers on astro ^7.0.0 (was >=6.4.0 <7.0.0) and builds against the Astro 7 ecosystem: @astrojs/mdx ^7, @astrojs/markdown-satteri ^0.3.4 (Sätteri ^0.9), Vite 8. The markdown pipeline — Sätteri plus the hastPlugins/mdastPlugins seam and Shiki dual-theme output — is unchanged; the Sätteri 0.6→0.9 jump left the plugin-definition types intact, so no seam code moved.

  Astro 7 makes Sätteri the default processor, which unblocks opt-in server output alongside it (the gate for hosted MCP, Ask AI, and content negotiation).

  Starter templates: Tailwind v4 now wires through @tailwindcss/vite instead of the PostCSS plugin, which does not build under Astro 7's Vite 8 bundler. Scaffolded projects gain @tailwindcss/vite and drop @tailwindcss/postcss + postcss.config.mjs.

  Breaking (peer): sites must be on Astro 7. The unified() escape hatch for remark/rehype plugins still works, but @astrojs/markdown-remark must now be installed explicitly (pnpm add @astrojs/markdown-remark) — pnpm does not expose it for import even though @astrojs/mdx pulls it transitively.

0.3.0

Minor Changes

• #9 d83ef06 Thanks @MohamedH1998! - Ship the static agent-surface layer: full corpus, raw-source twins, version labels

  • /llms-full.txt — the whole published site as one deterministic markdown document, via the new renderCorpusMarkdown() helper behind a ten-line starter route. Scope matches the root llms.txt (primary + secondary collections, non-current doc versions excluded); collation is sorted and timestamp-free, so output is byte-identical across rebuilds. /llms.txt links to it.
  • Raw-source twin at <page>/index.mdx — the authored MDX body served verbatim with the same canonical frontmatter block as the .md twin. Twin grammar: index.md is the downleveled render for reading, index.mdx is the source. The .md twin's Source: line now points at the .mdx twin instead of itself.
  • IndexedEntry gains sourceUrl (site-relative URL of the raw-source twin; undefined for entries without a string body) and version (the entry's version label resolved from the versions manifest; undefined on unversioned sites and non-docs collections). On versioned sites every twin's frontmatter carries a version: label so agents can pin a version; unversioned sites are byte-for-byte unchanged.
  • astro peer range is now >=6.4.0 <7.0.0, declaring the Astro 6 requirement that @astrojs/mdx@6 always implied. Astro 7 support lands as its own release.

0.2.1

Patch Changes

• #4 1ae3a78 Thanks @MohamedH1998! - Fix three defects found by post-0.2.0

  • Wide tables no longer overflow the page. A table with more columns than the content column could fit slid under the TOC rail and forced page-level horizontal scroll on desktop (the old scroll fallback only applied under 640px). A <table> can't both fill its column and scroll — overflow is ignored on display: table — so scroll now lives on a wrapper: nimbus-docs/markdown exports a tableScroll() hast plugin that wraps class-less tables in a .nb-table-scroll container, and the starter wires it up with matching styles. Short tables still fill the column with no dead space.
  • <Badge>label</Badge> renders its children. The text prop is now optional and falls back to <slot />; previously a slotted label was silently dropped and the badge rendered empty.
  • nimbus-docs add no longer crashes in non-TTY environments. A file conflict without --yes in CI, a pipe, or an agent crashed with a raw uv_tty_init returned EINVAL trace when the overwrite prompt tried to open a TTY that wasn't there. It now detects non-interactive stdin and exits with an actionable message pointing at --yes.

0.2.0

Minor Changes

• bd5411f Thanks @MohamedH1998! - Fetch templates at scaffold time from a tag-pinned source (giget)

  The CLI no longer bundles templates in its npm tarball. Templates are downloaded when you scaffold, pinned to the release tag matching the CLI's own version (create-nimbus-docs@0.2.0 fetches templates-v0.2.0) — reproducible forever, and old CLI versions are unaffected by new releases. Adds --template-dir <path> for fully offline scaffolding, and actionable errors for offline / missing-tag / rate-limited (403) fetches that name the tag tried, GIGET_AUTH, and --template-dir.

• 24113e0 Thanks @MohamedH1998! - Clear the Node and pnpm version gates that broke a fresh scaffold

  • Node floor raised to >=22.12.0. Astro requires Node ≥ 22.12; the old >=20.0.0 promise was a floor a scaffolded site could not actually build on (Node 20 is EOL and fails astro build with Node.js v20.x is not supported by Astro!). CI now runs Node 24 everywhere.
  • pnpm install no longer hard-fails under modern pnpm. pnpm ≥ 10 gates dependency install scripts and pnpm ≥ 11 turns an ignored build into a hard error (ERR_PNPM_IGNORED_BUILDS, exit 1). Scaffolded projects now ship a pnpm-workspace.yaml that declines exactly the packages with install scripts — esbuild and sharp (plus workerd on the Cloudflare target, which pulls wrangler) — never a blanket approval. All three ship working prebuilds, so the site still builds while the supply-chain surface stays minimal. Verified green on pnpm 9, 10, 11, and npm.