Configure Multiple Documentation Sites

CamelMind lets you publish multiple independent documentation sites from a single project.

Each documentation site can have its own:

• Navigation
• URL namespace
• Sidebar
• Content structure

You define each documentation site in versions.yml. For example, a project can publish:

• Product Documentation
• API Documentation
• SDK Documentation
• Internal Documentation

How to define multiple documentation sites in versions.yml

Define each documentation site as an entry in versions.yml. Each entry specifies a unique id, a display label, and the navigation file used by that documentation site.

versions:
  - id: docs
    stable: true
    label: "Documentation"
    nav: nav/docs.yml

  - id: api
    stable: true
    label: "API Reference"
    nav: nav/api.yml

Each versions.yml entry registers one documentation site. The nav field connects the site to its navigation file, which defines the site's page structure and sidebar.

How the stable field identifies the recommended documentation site

Set stable: true to mark a documentation site as the recommended site. CamelMind uses this flag for UI indicators, such as a Stable badge in the version selector.

The stable field does not affect routing, URL generation, or navigation.

versions:
  - id: docs
    stable: true
    label: "Documentation"
    nav: nav/docs.yml

How versions.yml and navigation files work together

The file versions.yml defines the published documentation sites and their respective navigation files.

Each navigation file defines the pages, URLs, and sidebar structure for its documentation site.

For example:

versions.yml
    ├── docs → nav/docs.yml
    ├── api  → nav/api.yml
    └── sdk  → nav/sdk.yml

This lets each documentation site have an independent page structure and sidebar while keeping all sites in the same project.

How CamelMind generates URLs for multiple documentation sites

CamelMind generates the final URL for each documentation site from its position and id in versions.yml.

Navigation entries define page slugs without URL prefixes. For example:

slug: /getting-started/overview

The first documentation site in versions.yml is the primary documentation site and keeps its navigation slugs unchanged. Additional documentation sites receive their id as a URL prefix.

For example:

versions:
  - id: docs
    label: "Documentation"
    nav: nav/docs.yml

  - id: api
    label: "API Reference"
    nav: nav/api.yml

  - id: sdk
    label: "SDK"
    nav: nav/sdk.yml

If each navigation file contains the same slug:

slug: /getting-started/overview

CamelMind generates these final URLs:

How the primary documentation site determines URL prefixes

The first documentation site listed in versions.yml is the primary documentation site.

The primary site uses its navigation slugs as-is and does not receive an id URL prefix.

For example, if the primary site's navigation contains:

slug: /getting-started/overview

the final URL is:

/getting-started/overview

How additional documentation sites use their id as a URL prefix

Additional documentation sites use their id as the URL prefix.

CamelMind publishes a documentation site with id: api and a navigation slug of /getting-started/overview at:

/api/getting-started/overview

CamelMind publishes a site with id: sdk and the same navigation slug at:

/sdk/getting-started/overview

You do not need to add these prefixes to the slug in the navigation file.

How each documentation site uses an independent navigation file

Each documentation site references its own navigation file in versions.yml. This lets each site organize its pages differently.

For example:

nav/
├── docs.yml
├── api.yml
└── sdk.yml

Each navigation file is independent:

• Product documentation can focus on tutorials and guides.
• API documentation can organize endpoints by resource.
• SDK documentation can group pages by programming language.

See Configure Navigation to learn how to structure each navigation file.

How to configure a single documentation site

If your project publishes only one documentation site, define one entry in versions.yml.

versions:
  - id: docs
    label: Documentation
    nav: nav/nav.yml

CamelMind publishes the single primary documentation site without an id URL prefix for its navigation slugs.

Most projects only need a single documentation site. Add additional entries when you want to publish separate documentation collections.

How to configure the default navigation file with navFile

CamelMind uses nav/nav.yml as the default navigation file for the primary documentation site.

You can change the default navigation file in camelmind.config.ts with the navFile setting.

const config: CamelMindConfig = {
  navFile: "nav/nav.yml",
}

Common multiple documentation site configurations

Choose the documentation site structure that matches how you want to organize and publish your content.