Versions

URLs#

The latest docs live at /docs. Each older version keeps its own copy under /docs/v<version>:

/docs/components/button          latest
/docs/v0.1/components/button     v0.1
/docs/v0.1/components/button.md  v0.1 as Markdown

Older versions are frozen exactly as they were published, including their styles and scripts, so their examples keep working after later releases change the components. They show a notice linking to the same page in the latest version, and ask search engines not to index them.

Switching versions#

The switcher keeps you on the same page when it exists in the version you pick, and goes to that version's introduction otherwise. Older versions list newer releases too, because the list is read from /docs/versions.json when the page loads.

Version links are never htmx-boosted: each version carries its own theme, styles and scripts, so a switch is a full page load (hx-boost="false") rather than a body swap under the stylesheet you are already wearing.

Versioning policy#

• Releases follow semantic versioning. Docs are versioned per minor release (0.1, 0.2, …) before 1.0, and per major release after.
• Patch releases update the docs of their version in place.
• The version under development has no number yet and is listed as next until it is released.
• Every release's changes and migration notes are in the changelog.

How it works#

The versions plugin (htmx-ui-plugin-versions) does all of this: it serves the frozen versions, publishes the manifest the switcher reads, and freezes a version with htmx-ui versions:archive when the next one starts. Add it to your own site to version its docs the same way.

For tools and agents#

/docs/versions.json lists every version with its URL prefix, its own sitemap (with section text, for search) and the pages it contains:

{
  "latest": "0.2",
  "versions": [
    { "id": "0.2", "label": "v0.2", "path": "/docs", "latest": true, "sitemap": "/docs/sitemap.json", "pages": ["", "/installation", "…"] },
    { "id": "0.1", "label": "v0.1", "path": "/docs/v0.1", "latest": false, "sitemap": "/docs/v0.1/sitemap.json", "pages": ["", "…"] }
  ]
}