Versioning

Hudocs supports multi-version documentation sites through separate directories within content/docs/. Each directory represents an isolated version and maintains its own content, navigation structure, and search index.

Version Architecture #

In Hudocs, documentation versions correspond to subdirectories within content/docs/:

content/
└── docs/
    ├── _index.md
    ├── latest/
    │   ├── _index.md
    │   └── ...
    ├── 1.8/
    │   ├── _index.md
    │   └── ...
    └── 1.0/
        ├── _index.md
        └── ...

Hugo manages each version directory as an independent subsection under docs. This keeps the content, sidebar tree, and search index of each version separated.

Version Selector #

The version selector in the header displays the identifier of the current version, such as latest or 1.8. Selecting it displays the available versions.

Automatic Version Detection #

If you do not define the docs_versions parameter, Hudocs automatically detects versions from the subsections under content/docs/:

<a href="/docs/latest/">latest</a>
<a href="/docs/1.8/">1.8</a>
<a href="/docs/1.0/">1.0</a>

Explicit Version List #

To define which versions appear in the selector and set their order, configure docs_versions:

docs_versions = ["latest", "1.8", "1.0"]

Creating and Archiving Versions #

To publish a new version while keeping previous versions available:

Documentation Landing Page #

When a user accesses /docs/, Hudocs uses layouts/docs/list.html to display a directory page with the list of documented versions.