Skip to content
✨ Publier v1 is live — a polished docs platform built for the open web.
On this page

Versioning

Publish documentation versions and configure independent product version selectors in the documentation header.

Publier can link readers to parallel documentation trees. Configure a product’s versions in the top navigation, or keep a shared version list for a single product. These controls link to published pages; they do not generate or archive content.

Product-aware top navigation

Add products to the navigation variant used by your documentation. Each product chooses whether it has a version list:

publier.config.yaml
nav:
  docs:
    title: Acme Docs
    products:
      - label: Compute
        path: /docs/compute
        href: /docs/compute/v2
        versions:
          - { label: v2, path: /docs/compute/v2, badge: stable, default: true }
          - { label: v1, path: /docs/compute/v1, badge: legacy }
      - { label: Enterprise, path: /docs/enterprise }

Compute shows its own versions. Enterprise has no version selector. To show only a version dropdown, configure one product. To show neither dropdown, omit products or set it to [], and leave any legacy docs.sidebar.versions list empty.

The current URL selects the product and version by longest matching prefix, respecting path segment boundaries. A version’s default: true is a fallback when no version path matches; it does not override a URL match. Selecting a version navigates to its configured path. Choose a real landing page for each version rather than assuming every version contains the current article.

Use navigation variants and path rules to keep these selectors in the docs area of a site that also has marketing pages.

Publish the destinations

With Publier’s default /docs/[...slug] route, the content directory determines the URL:

src/content/docs/
├── compute/
│   ├── v1/
│   │   ├── index.mdx        → /docs/compute/v1
│   │   └── introduction.mdx → /docs/compute/v1/introduction
│   └── v2/
│       ├── index.mdx        → /docs/compute/v2
│       └── introduction.mdx → /docs/compute/v2/introduction
└── enterprise/
    └── index.mdx            → /docs/enterprise

Each page needs normal documentation frontmatter, including title. Keep the content for each version appropriate to that release. Check the landing destinations and representative internal links before publishing. If you publish version trees elsewhere, supply paths that match your own routes.

Version selectors link to their destinations without filtering sidebar content. Use docs.tabSections for version folders that need separate sidebars, as described in global settings. Product tab destinations under /docs/ automatically supply sidebar scopes in the default route from shell 4.3.2/native 6.0.1; those paths do not need duplicate tabSections entries.

Shared version list

For an existing site with one shared version list, the legacy docs.sidebar.versions configuration remains supported. The default docs route now renders this list in the header:

publier.config.yaml
docs:
  sidebar:
    versions:
      - { label: v2, path: /docs/v2, badge: stable, default: true }
      - { label: v1, path: /docs/v1, badge: legacy }

This list is site-wide; it is not an independent list per product. A configured product list takes precedence, so the default docs route does not duplicate selectors. Prefer nav.docs.products for new sites. To show neither selector, omit both products and the legacy version list. You can still render VersionSwitcher directly in a custom layout.

What to manage separately

Content snapshots, redirects such as /latest, and version lifecycle policies remain part of your publishing workflow. Publier’s selectors provide navigation to the destinations you configure. They do not fetch other branches, clone documentation trees, or create redirects.