Nimbus Documentation Framework

The VersionSwitcher is a UI component used to provide a header dropdown for desktop users and a sidebar control for mobile users to switch between different documentation versions. It integrates with the framework's data layer using getVersions, getVersionAlternates, and getCurrentVersion.

Note: The component will render nothing if the site is unversioned or contains only a single version.

Unlike traditional documentation themes that rely on an upstream package for styling and layout, Nimbus follows an 'ownership' model:

• Code Ownership: The scaffolder writes layouts, components, and styles directly into your repository as real files. You can edit any file without waiting for upstream updates or forking a theme.
• Agent-First Design: Every page is optimized for both humans and AI agents by providing .md alternates, a /llms.txt index, and JSON-LD in the document head.
• Agentic Extensions: The nimbus-docs add command allows you to pull from a registry. It operates in two modes: copying components as files or handing off recipes that a coding agent can read and apply.

The banner frontmatter configuration is applied on a per-page basis. To display a notice across the entire site, you should not use frontmatter. Instead, use one of the following methods:

1. Render the Banner component directly within your BaseLayout.
2. Add a persistent element through the head configuration.

The new-collection recipe is intended for non-versioned content trees such as blogs, API references, changelogs, or glossaries.

If you are trying to add a version of the documentation (e.g., a frozen snapshot of v1 while you work on v2), do not use this recipe. Instead, use the dedicated command:

nimbus-docs add new-version

This command handles the version manifest, installs the version picker, and wires it into the header and sidebar, which the generic collection recipe does not do.

If you want to use a different backend (such as Algolia or a custom hosted service) while keeping the Nimbus search UI, you can implement the SearchProvider interface.

To use a custom provider:

1. Implement the SearchProvider interface.
2. Set search: { provider: "custom" } in your configuration.

When using a custom provider, Nimbus skips the Pagefind build step and relies on your implementation to render results.

nimbus({
  // ...
  search: {
    provider: "custom"
  }
});

When adding a version to your manifest, you can specify its visibility and status to control user experience and search indexing:

• Deprecated Versions: Adding a slug to versions.deprecated triggers a yellow caution banner on all pages within that version, adds a deprecated badge to the version picker, and excludes the version from default Pagefind search results. This is ideal for End-of-Life (EOL) documentation.
• Hidden Versions: Adding a slug to versions.hidden makes the version's URLs resolvable but excludes it from the version picker dropdown, the Pagefind search index, /llms.txt files, and cross-version <link rel="alternate"> tags. This is useful for drafts or private versions.

When building the body of an overview page, choose between Cards/CardGrid and Link lists based on density:

• Cards / CardGrid: The signature component for overviews. Use these when routing is the body. Keep card text to a name plus one line. Note: Write one-liners so they work in both the visual card form and the .md twin (where they flatten to link-plus-description lists).
• Link lists: Use these when a grid forces too much padding or when you have more than ~5 links in a group. Prose lists scan better at high volumes.

When building Example pages, follow these component and formatting patterns to ensure compatibility with both human readers and AI agents:

• Titled Code Blocks: Always use title="filename" (e.g., title="app/api/route.ts") to provide essential context.
• In-code Comments: Use comments inside the code block for point-of-use notes (e.g., // rejects deliveries signed >5 min ago) so they survive copy-pasting.
• Placeholders: Use <angle-brackets> for placeholders where a real value cannot exist. Use realistic values everywhere else.
• Structure: Follow the sequence: Shown result $\rightarrow$ How-it-works (bullets for non-obvious lines) $\rightarrow$ See also.

When adding a new collection, follow these naming and routing rules to ensure compatibility with Nimbus:

Collection Name Requirements

• Must be lowercase.
• Must contain only a-z, 0-9, -, or _.
• Must not collide with existing collections in src/content.config.ts.
• Reserved names: Do not use docs or partials.
• Excluded prefix: Do not start a name with _ (this prefix is used for collections that are loaded but excluded from indexing).

URL Prefixing

The URL prefix is the path segment where the collection mounts.

• For a blog collection with prefix /blog, a file at src/content/blog/foo.mdx renders at /blog/foo.
• Versioning Convention: If a collection name starts with docs- (e.g., docs-v1), the URL prefix should default to the part after the prefix (e.g., /v1/). A docs-v1 collection mounts at /v1/, not /docs-v1/.

Tutorials should use registered MDX components found in src/components.ts. Common components for tutorials include:

• Steps / Step: For numbered instructional parts.
• Fenced code blocks: For verbatim "You should see" output.
• PackageManagers: For pinned installation commands.
• Aside: Used sparingly for minor notes.

Note: Avoid using Tabs in tutorials. If different stacks require different narratives, create separate sibling pages instead of using variant tabs.