@cloudflare/nimbus-docs@0.17.0

Minor Changes

• #204 a8e0d02 Thanks @MohamedH1998! - - Agent files follow the rendering policy: a page's index.md/index.mdx renders in its collection's mode, a section's llms.txt in the mode of the collection it lists, llms.txt/llms-full.txt in rendering.default, and homepage Markdown in the root collection's mode. Mounted collections get their own agent routes, copied starter routes keep working unchanged, and static sites don't change.

• #201 855091c Thanks @MohamedH1998! - Add samples.generate to choose which languages Nimbus generates code samples in, and fix generated samples and examples that sent different values from the page.

  • samples.generate: set samples: { generate: ["curl"] } on an api entry to generate only a cURL request, instead of cURL, TypeScript, and Python, on every operation. [] generates none, so operations show only their authored x-codeSamples. The default is unchanged: all three. samples.keepGenerated still picks the generated languages shown next to authored samples; each of its languages must now also be in generate.
  • Python and TypeScript bodies: in Python, a string containing a newline, carriage return, or tab no longer breaks the sample with a SyntaxError, and object keys with quotes or backslashes stay valid. In both languages, a backslash is no longer read as an escape (C:\\temp\\new was sent with a tab and a newline), including in text bodies such as text/plain. A JSON body of false, 0, or "" is now sent instead of dropped.
  • cURL bodies: a body containing ' was passed through an unquoted heredoc, so the shell collapsed backslashes and ran $NAME and backticks in the example when the sample was pasted. The heredoc is now quoted.
  • Form bodies: application/x-www-form-urlencoded bodies were dropped from every sample and are now sent in all three languages. A property with an encoding entry follows OpenAPI: style, explode, or allowReserved select query-style serialization, and an entry without them sends the value as its contentType, so an object is sent as JSON. A property without an entry nests objects in brackets (metadata[plan]=pro), repeats the name for each item of a scalar array (tags=a&tags=b), and indexes arrays of objects (items[0][price]=p_1). A string example is read as an encoded form; a form example with no fields sends no body. multipart/form-data bodies are still omitted.
  • Form encoding: explicit JSON content types serialize scalar values as JSON before form encoding. allowReserved: true preserves valid percent-encoded triples and safe reserved characters without double encoding; form delimiters and unsafe characters remain encoded.
  • cURL text bodies: a body starting with @ is sent as text instead of uploading the file it names.
  • Joined form values: a ,, |, or space inside an array item no longer reads as a separator with explode: false, unless allowReserved: true leaves a , unencoded.
  • Empty form field names: cURL now sends =value like the other languages.
  • Request example: an operation without code samples, such as with samples.generate: [], shows its request example on the page.
  • Swagger 2.0: a Swagger 2.0 document now fails the build with Swagger 2.0 isn't supported. Convert it to OpenAPI 3.x first. and the document's path, instead of building pages with no server URL, unknown parameter types, and missing response schemas. The API reference docs show how to convert one before each build.

  If the installed httpsnippet writes a body differently from the layout Nimbus corrects, that language's sample is left out rather than shown with an unescaped body. Authored x-codeSamples are unchanged. New sites scaffolded by create-nimbus-docs use this release.

• #207 d77ff08 Thanks @MohamedH1998! - - A request-rendered API family can set versionMode: "query": one URL per operation, the version in ?api-version= (absent means the default, unknown is 404, hidden versions reachable by query only). Generated same-version links carry the query; discovery covers the default version at version-free URLs; non-default pages are noindex with the default counterpart as canonical. Path mode stays the default and is unchanged.

  • API version ids may contain dots, and must start and end with a letter or digit. An id like -v1 or v1- now fails validation; rename it.

• #198 86b573a Thanks @MohamedH1998! - - Skills in skills/<name>/SKILL.md folders are published at /.well-known/agent-skills/ with a discovery index, archives for multi-file skills, and digests.

• #199 b8a8dbd Thanks @MohamedH1998! - - Sites with API collections publish every spec, including hidden versions, as one self-contained openapi.json at its mount path, and list each visible API in an RFC 9727 catalog at /.well-known/api-catalog. Set publishSpec: false to keep a spec private.

• #195 b685092 Thanks @MohamedH1998! - - Add discovery files, homepage Markdown, and Link headers to all sites.

  • Add editable Content Signals to the starter's robots.txt.

• #205 7b76521 Thanks @MohamedH1998! - - Sidebar groups are native details/summary with one class per row type, a CSS caret, and no animation; a group's landing page lists as an "Overview" child row. Each page renders one sidebar tree, shared by the desktop rail and the mobile drawer, and a large sidebar's page HTML drops by roughly 80%. The state scripts drive the old copied markup too.

• #203 62d7956 Thanks @MohamedH1998! - - Only collections made with Nimbus's helpers (docsCollection(), componentsCollection(), withNimbusMarkdown()) become pages; every other collection is plain Astro data with no naming rule, and the _ prefix convention is removed. If rendering is set, a site's own page collection with a catch-all route now needs an entry in rendering.collections.

• #196 2e200ce Thanks @MohamedH1998! - - The starter registers a search_documentation WebMCP tool, backed by the site's Pagefind index.

• #200 c17a945 Thanks @MohamedH1998! - - On server output, a request-rendered page returns its Markdown when the request prefers text/markdown; the URL stays canonical and both forms send Vary: Accept.

  • The starter homepage renders on request when a collection already does under server output, so it negotiates too. All-build homepages remain prerendered in production.
  • Preserve owner static-header rules while adding discovery fields, and support prose request rendering and published Markdown negotiation through Astro adapters and standard HTTP on non-Cloudflare deployments.
  • Recreate the isolated browser-agent Pagefind instance after observable search failures and give accurate connection/reload guidance. Pagefind's swallowed index-chunk failures remain a documented upstream limitation.
  • Include a release-matched agent-interface guide in the framework package and point generated project instructions to it.

Patch Changes

• #201 7b8c3e8 Thanks @MohamedH1998! - For methods that support request bodies, preserve JSON null in generated TypeScript and
  Python samples. They now send the same four-byte JSON payload as cURL instead of omitting it.
  Absent request bodies remain absent, and schema-derived examples and authored code samples
  keep their existing behavior.

• #193 bcc1b1e Thanks @sansynx! - Keep synced tabs usable when browser storage writes fail because the storage quota is full.

• #206 bcfe446 Thanks @MohamedH1998! - - The version picker keeps a reader on the same operation when its operationId changed between versions but its HTTP method and path shape did not (including a renamed path parameter). The pairing is order-independent and never guesses: anything ambiguous stays unmatched and goes to the version landing, as before.