Versioned documentation with folders per version

1 minute read

This recipe shows how to host several versions of your documentation (/v1/, /v2/, and /latest/) from one repository. A version is a folder of pages; the engine publishes each folder at its path, so v1/index.md is /v1/ and v2/guide.md is /v2/guide/.

Keep latest as a redirect

Write each version under its own folder, then make latest an old path that redirects to the current version in mizzen.yml:

redirects:
  /latest/: /v2/

Alternatively, add latest/index.md with redirect_to: /v2/ in its front matter.

Add a version switcher

List the versions in _data/navigation.yml. URLs are written without base; the engine adds it.

main:
  - title: Latest (v2)
    url: /v2/
  - title: Version 1 (v1)
    url: /v1/

When the site is published under a project path, set base once in mizzen.yml, such as /my-project; do not repeat it in navigation URLs. A build fails when two pages write the same URL, so keep the version folders and their index.md files distinct.

View Markdown

Use with an agent
View Markdown

Open in