# Versioning

> Publish docs for several releases side by side with sections or separate deploys.

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](/customization/article-sections/#changelog-sections) 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:

- getting-started.html

- v1

  - index.html
  - getting-started.html

**htmlpress.yaml**

```yaml
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:

**HTML**

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

**Markdown**

```md
:::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`](/deployment/github-pages/#configure-base-for-project-sites).

**htmlpress.yaml (v1 branch)**

```yaml
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](/customization/external-links/), which acts as a version switcher:

**htmlpress.yaml (main branch)**

```yaml
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](/deployment/) for host setups. Most hosts deploy branches to their own URLs out of the box.

## See also

- [Article Sections](/customization/article-sections/): section types, prefixes and matching.
- [Site Metadata](/customization/site-metadata/): the `banner`, `title` and `site` fields used above.