Versioning

Htmlpress has no dedicated versioning feature: the building blocks it already has cover the two common shapes. Pick by how far apart your versions are:

• One site, a section per version: a few versions whose docs live on one branch.
• One deploy per version: long-lived majors maintained on their own branches.

Most projects only need to keep the latest docs plus the previous major. If old releases only need their notes, a changelog section is enough.

A section per version

Keep each older version's pages in a folder of its own. The current docs stay at /, and each older version becomes a section:

title: Acme
sections:
  - title: Docs
    prefix: /
  - title: v1
    prefix: /v1/
    icon: archive
    siteTitle: Acme v1

Longest-prefix matching routes every /v1/… page into the v1 section, so it gets its own sidebar while the rest of the site keeps the current docs. siteTitle relabels the brand next to the logo inside that section, so a reader always sees which version they are on. Set position: sidebar to keep version tabs out of the header.

To warn readers on old pages, start each with a callout:

<htmlpress-callout type="warning">
  <p>You are reading the docs for v1. <a href="/getting-started/">See the latest version</a>.</p>
</htmlpress-callout>

:::warning
You are reading the docs for v1. [See the latest version](/getting-started/).
:::

Things to know:

• Search indexes the whole site, so results include every version's pages.
• Copying a folder per version duplicates content; freeze the old folder and only fix it when necessary.

One deploy per version

When each major lives on its own branch (main, v1, …), build each branch as its own site and serve it from its own address: a subdomain (v1.docs.example.com) or a sub-path (docs.example.com/v1/) with base.

site: https://docs.example.com
base: /v1/
title: Acme v1
banner: You are reading the v1 docs · <a href="https://docs.example.com/">Go to the latest →</a>

htmlpress start and preview serve under the same base, so the branch previews exactly as it deploys. Link the deploys to each other with a custom section or a header link, which acts as a version switcher:

sections:
  - title: Docs
    prefix: /
  - title: v1
    type: custom
    url: https://docs.example.com/v1/
    icon: archive

Each deploy has its own search index, sitemap and llms.txt, so versions never mix. The cost is one build and one CI job per maintained branch; see Deployment for host setups. Most hosts deploy branches to their own URLs out of the box.

See also

• Article Sections: section types, prefixes and matching.
• Site Metadata: the banner, title and site fields used above.