nimbus-docs 0.18.0

Minor Changes

• #229 a04304c Thanks @MohamedH1998! - - A page or reusable snippet with only frontmatter builds, and its Markdown version is just its title and source.

  • A snippet included inside a list item or quote keeps that structure in the page’s Markdown version.
  • llms.txt names each section for its index page’s title, such as “Guides” instead of guides.
  • Documentation search results link to the page itself instead of a URL ending in #, and excerpts no longer include the page actions.
  • The Markdown version of an API page names each field as the page does, with its full coordinate beside it for citing.

• #232 d655e86 Thanks @MohamedH1998! - - API pages link to the previous and next page in sidebar order, even when a group is collapsed.

  • Error responses start collapsed; a link to one, or to a field inside it, opens it.
  • A sidebar link to an API or docs-version mount, such as /api, no longer warns.
  • Operations that fall back to a coordinate route print one summary line, so other warnings stay visible.
  • Samples and the endpoint card keep a server URL’s query after the path.
  • Response toggles meet 4.5:1 contrast in light mode, field anchors work on touch screens, and “Authorisation” reads “Authorization”.

• #211 4a841cb Thanks @MohamedH1998! - - Add bundle: false to an api entry to serve a very large or many-version API from static assets instead of the server bundle. Unchanged pages are shared across versions, and unchanged versions aren’t prepared again on rebuild. Needs src/live.config.ts registering apiPagesLoader from @cloudflare/nimbus-docs/live; the build shows the snippet. The build suggests the option when an API’s bundled page data passes 16 MiB.

  • Add getVersionSwitchUrl and getApiVersionHead for version pickers and heads in every rendering mode; the starter’s picker and API layout use them.

• #212 94ebe52 Thanks @MohamedH1998! - API pages show the sidebar filter. With sidebar: "on-demand" it also finds pages the sidebar hasn’t loaded.

• #222 e15eea7 Thanks @MohamedH1998! - New api[].extensions option: list the x-* fields to keep, and their values are copied onto API pages as page.extensions and field.extensions for your components to render.

• #214 825ffcf Thanks @MohamedH1998! - API reference pages show the version picker for versioned APIs, in the sidebar and the mobile navigation.

• #211 02f53a1 Thanks @MohamedH1998! - versionMode is now versionUrl: versionUrl: { in: "query" } selects the version with ?version= instead of ?api-version=, and old links redirect. Set param to use another name (review entry api-version-url).

• #240 381b37a Thanks @MohamedH1998! - - og:image:width and og:image:height describe the image: generated cards stay 1200 × 630, a socialImage file in public/ is measured at build time, and any other image gets no size tags. NimbusHead takes socialImageSize to set them for an image Nimbus can’t measure.

  • The sitemap has <lastmod> on every documentation page, from frontmatter lastUpdated or the page’s last commit, and /sitemap.xml is a copy of sitemap-index.xml unless the site serves its own.
  • The starter’s BaseLayout passes socialImageSize through to NimbusHead, and the 404 page recipe writes the new title and noindex.
  • On a shallow clone, pages get no git dates instead of the wrong one, and the build says how to fetch the history.
  • The 404 page’s title is Page not found | <site> and the page is noindex.

• #233 1f2ce43 Thanks @MohamedH1998! - - New sites open content images at full size on click. On an existing site, run nimbus-docs add image-zoom and render <ImageZoom /> in src/layouts/DocsLayout.astro.

• #238 315ab66 Thanks @MohamedH1998! - - A resource-action-v2 route convention publishes tag pages at lowercase URLs, such as /api/tags/user-management, with the same operation URLs as resource-action-v1. Existing conventions, and sites without routes, are unchanged.

  • The API reference recipe sets resource-action-v2 on new sites and resolves the route collisions the build reports.

• #224 79b05ef Thanks @MohamedH1998! - - New markdown.features option turns on Sätteri syntax, such as { headingAttributes: true } for ## Install {#install} or { math: true }. Pages, generated Markdown, reusable snippets and lint all follow it. New sites start with heading ids on.

  • Generated Markdown drops {/* comments */}.
  • Invalid MDX reports the file, line and fix instead of an internal error.

• #226 dd95e97 Thanks @MohamedH1998! - - New math() Markdown plugin typesets $…$, $$…$$ and ```math at build time as native MathML, with no math JavaScript. Add math() to markdown.hastPlugins and math: true to markdown.features to use it.

• #236 fb759c5 Thanks @MohamedH1998! - - With the section route at src/pages/[...section]/llms.txt.ts, each sub-folder gets its own llms.txt, and its parent’s index links to it under “Sections”. New sites have this route; a [section] route keeps today’s one index per top-level section.

  • An llms-full.txt over 25 MiB becomes an index of one llms-full.txt per section, split further where a section is still too big, so the site deploys to Cloudflare.
  • LlmsEndpointReference (from @cloudflare/nimbus-docs/agent-endpoints) adds surface: "full" on section references, for the per-section llms-full.txt files.

• #224 79b05ef Thanks @MohamedH1998! - Starter fixes:

  • The theme toggle no longer submits a surrounding form, reports its state to screen readers, and still switches when storage is blocked.
  • Closing a dialog no longer releases another overlay’s scroll lock.
  • “Copy page” works in Safari, and a failed command copy shows it failed.
  • In search, Enter on the close button closes the dialog, and status messages are announced.
  • <Render> params can’t replace registered components; small fixes to breadcrumbs and the mobile table of contents.
  • Banner content is rendered as written, like the rest of the site’s content.

• #223 c39fdfc Thanks @MohamedH1998! - The docs version picker no longer appears on pages outside the docs versions, such as API reference and blog pages.

Patch Changes

• #228 6d4bd68 Thanks @MohamedH1998! - - add reports components whose files already match the registry as up to date, and --overwrite lists each file it replaces, asking first in a terminal when you’ve edited the component.

  • add --overwrite detects edits to components that came with the starter from the starter release your site came from, so it replaces untouched ones without asking.
  • add adds a component’s missing files even when it keeps your edited ones, and lists each file it adds, replaces or keeps.
  • add no longer suggests registering a component that components.ts already registers.
  • Upgrade reviews about API reference pages are skipped on sites without an API collection.
  • outdated says when a newer Nimbus is out, when the reviewed version only needs recording, and when a registry dependency is installed below the version a component needs.
  • diff --apply on a file only you changed reports there’s nothing to pull, without failing.
  • diff, outdated and migrate explain preview builds instead of asking for a baseline.

• #219 942c57b Thanks @MohamedH1998! - Generated code samples for multipart/form-data request bodies now send every part, with file fields as <name> placeholders, instead of only the Content-Type header.

• #223 c39fdfc Thanks @MohamedH1998! - - Generated API samples use <base-url> when a spec has no server or a relative one, instead of an invented host, and fill server variables from their defaults.

  • OpenAPI 3.2 tag parent no longer prints a warning for each tag that uses it.
  • nimbus-docs add api-layout ends by pointing to the API route instead of src/components.ts.
  • The Markdown version of an API page fences cURL samples as bash.

• #220 cd7f0da Thanks @MohamedH1998! - - Request field lists no longer show properties marked readOnly across schema alternatives, and response field lists no longer show those marked writeOnly across alternatives. Synthesized examples use the selected alternative; authored examples retain their values. Webhook payloads read like responses. Cite a readOnly field under the response.

  • A string example under a non-JSON media type such as application/x-ndjson is sent verbatim in generated samples.
  • Object form examples with media-type parameters such as ; charset=utf-8 generate per-field samples; authored encoded strings keep their bytes.

• #234 1b546af Thanks @MohamedH1998! - - astro dev and astro check no longer delete the build’s page-collection list, so nimbus-docs check runs its page-collection checks after a build.

  • nimbus-docs lint and check say when the lint rules in your Astro config changed since .nimbus/lint.json was written, and to run astro sync.
  • check marks a scope that skipped some checks ◐ ok, partly checked, and says --types covers .ts and .tsx files only (run astro check for .astro).
  • nimbus-docs check --help lists check’s own flags.
  • The adapter warning for @astrojs/cloudflare 14.2.x says only a cold astro dev can fail; builds aren’t affected.
  • An invalid API spec, such as Swagger 2.0, fails the build with its message and no stack trace.
  • Request-rendered routes that export getStaticPaths() get one line explaining that the rendering policy renders them on request.
  • On a static Cloudflare site with trailingSlash: "always" and build.format: "file", the build and check warn that every /page/ link redirects, and name the wrangler.jsonc fix.
  • Repeated API spec warnings that differ only by source print once, with a count.
  • lint --rule nimbus/mdx-syntax says the syntax check always runs.

• #211 ff1cd57 Thanks @MohamedH1998! - Load @iconify-json icon sets from the site root, so a build started from another directory still finds them.

• #237 7a07851 Thanks @MohamedH1998! - - Search is indexed however astro build is started, including ./node_modules/.bin/astro build.

  • A site’s pagefind.yml applies when the build starts from another folder with --root.
  • The build says to install Pagefind only when it isn’t installed.

• #230 25d21cf Thanks @MohamedH1998! - - Server scaffolds for Node, Vercel, and Netlify render docs pages on request, so Markdown negotiation works on them.

  • Scaffold into . or an empty folder, including a freshly cloned repository.
  • New repositories get a first commit; scaffolding inside an existing repository no longer creates a nested one.
  • npm create installs a handful of packages instead of the whole framework.
  • A missing package manager fails before anything is written, and a mistyped flag suggests the right one.
  • Yarn sites ignore .yarn/ the way Yarn recommends, and pin Yarn inside a folder that pins another package manager.
  • The starter’s AGENT.md explains sidebar groups, order, and links.
  • nimbus-docs check and --help show commands for your package manager.

• #213 7350707 Thanks @MohamedH1998! - When an API’s spec can’t be published because a $ref isn’t a reference string, the build warning names where it is instead of printing [object Object].

• #227 ea8712d Thanks @sansynx! - Add UTF-8 Content-Type headers for prerendered llms indexes, full documents, page Markdown, and robots.txt. Keep rules scoped to Nimbus file paths and preserve explicit owner Content-Type policies.