Versioning

Show multiple documentation versions side by side using the VersionSwitcher component.

Publier ships a VersionSwitcher component — a dropdown that lives at the top of the sidebar and lets readers jump between parallel documentation trees (e.g. /v1/, /v2/, /latest).

Canonical wiring: publier.config.yaml#docs.sidebar.versions

Publier reads docs.sidebar.versions from publier.config.yaml and feeds it to the sidebar automatically. Zero layout code needed:

docs:
  sidebar:
    versions:
      - { label: "v2.0",    path: /,    badge: stable,     default: true }
      - { label: "v1.5",    path: /v1,  badge: legacy }
      - { label: "beta",    path: /beta, badge: beta }

The sidebar’s active-path highlighting re-syncs on client-side navigation, so the version badge and current-page marker both stay accurate without a page reload.

Overriding the default route

If you need custom sidebar behaviour beyond what the config exposes, drop src/pages/docs/[...slug].astro into your project — your file takes precedence over Publier’s default route. Then you can pass versions directly to <Sidebar> in that file:

---
import { Sidebar } from '@publier/shell/components';
import BaseLayout from '@publier/shell/layouts/base-layout.astro';

const versions = [
  { label: 'v2.0', path: '/', badge: 'stable' as const, default: true },
  { label: 'v1.5', path: '/v1', badge: 'legacy' as const },
  { label: 'beta', path: '/beta', badge: 'beta' as const },
];

const sidebarItems = /* build or import your sidebar entries */;
---

<BaseLayout title="Docs" nav="docs">
  <Sidebar items={sidebarItems} currentPath={Astro.url.pathname} versions={versions} client:load />
</BaseLayout>

Standalone VersionSwitcher

If you’re building a custom nav that doesn’t use Sidebar, render VersionSwitcher directly anywhere — the component is fully self-contained:

---
import { VersionSwitcher } from '@publier/shell/components';

const versions = [
  { label: 'v2.0', path: '/', badge: 'stable' as const, default: true },
  { label: 'v1.5', path: '/v1', badge: 'legacy' as const },
];
---

<VersionSwitcher versions={versions} currentPath={Astro.url.pathname} client:load />

The component auto-selects the active version by longest-prefix match on currentPath.

Props

VersionSwitcher

DocVersion

Directory layout per version

Each version maps to a top-level directory under src/content/docs/:

my-site/
└── src/
    └── content/
        └── docs/
            ├── v1/              ← /v1/*
            │   ├── meta.yaml
            │   ├── introduction.mdx
            │   └── ...
            ├── v2/              ← /v2/*
            │   ├── meta.yaml
            │   └── ...
            └── ...              ← also /docs/* for "latest"

The sidebar auto-detects each directory as a section. Give each version’s meta.yaml a title: field matching the version label so the sidebar group is labeled accordingly — meta.yaml title: controls the sidebar group’s display name (distinct from an individual page’s frontmatter title).

”Latest” aliasing

A common pattern is to publish the current stable version twice — once at / (so old links keep working) and once under its explicit version path (so history is reachable). Copy the current version’s MDX tree into both directories, or use a build-time script to clone it. Declarative support for latest aliases is planned alongside the versions: config key.

Roadmap

• Declarative config — versions: block in publier.config.yaml that wires the switcher without a custom layout.
• Per-version content sources — point each version at a git branch or a separate content directory so the MDX files don’t have to live in the main tree.
• Automatic “latest” redirects — latest path alias with 301 emission.

Questions on versioning or roadmap items? Email [email protected].