cloudflare/nimbus @cloudflare/nimbus-docs@0.19.0

on GitHub

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.