Versions plugin · HTMX UI

htmx-ui-plugin-versions keeps the docs of every release online. The version being written renders live at /docs, as usual. Each older one is a frozen build in archive/v<id>/, served at /docs/v<id>/: its pages, scripts and styles exactly as they were released, so later changes to components or layouts can never break them. This website's versions work this way.

Install#

bun add htmx-ui-plugin-versions

npm install htmx-ui-plugin-versions

pnpm add htmx-ui-plugin-versions

yarn add htmx-ui-plugin-versions

htmx-ui.config.ts

import { defineConfig } from "htmx-ui-engine";
import docs from "htmx-ui-plugin-docs";
import versions from "htmx-ui-plugin-versions";

export default defineConfig({
  plugins: [docs(), versions()],
});

List the versions. The one being written has no number yet; it is next until it is released:

data/versions.json

{
  "latest": "next",
  "versions": [{ "id": "next", "label": "next" }]
}

styles.css

@import "tailwindcss";
@import "htmx-ui/styles.css";
@import "htmx-ui-plugin-versions/styles.css";

app.ts

import { initVersions } from "htmx-ui-plugin-versions/client";

document.addEventListener("DOMContentLoaded", () => initVersions());

It works without the docs plugin, but with it each archived version also keeps its Markdown and its own sitemap, the sitemaps list every version, and search follows the version being read.

The switcher and the banner#

layouts/docs.html

{% from "versions/macros.html" import version_switcher, version_banner %}

<aside>
  {{ version_switcher(class="mb-6 w-full", links=[{ title: "Changelog", href: "/docs/changelog" }]) }}
</aside>
<article>
  {{ version_banner() }}
  <h1>{{ title }}</h1>
</article>

Template	Description
`version_switcher(class, links)`	A Dropdown listing every version. links are extra entries under a separator: [{ title, href }]. At runtime the client points each version at the same page when it exists there, and adds versions released after the page was built.
`version_banner()`	Where an archived page's "you're viewing an old version" notice goes, linking to the same page in the latest version. Empty on the latest docs.
`docsVersions()`	The versions file as templates see it: latest, current, label, manifest and versions (id, label, released, path, latest).

Archiving bakes the banner into every frozen page, so it shows without JavaScript. The client only refreshes it, so an old version learns about releases that came after it.

Releasing a version#

The plugin adds two CLI commands. Give them scripts, so they run on the runtime you build with:

package.json

{
  "scripts": {
    "docs:name": "htmx-ui versions:name",
    "docs:archive": "htmx-ui versions:archive"
  }
}

bun run docs:name 1.2.0
bun run docs:archive

npm run docs:name 1.2.0
npm run docs:archive

pnpm run docs:name 1.2.0
pnpm run docs:archive

yarn run docs:name 1.2.0
yarn run docs:archive

versions:name <x.y.z> numbers next and dates it today. Docs are versioned per minor before 1.0 (0.2.0 becomes 0.2) and per major after (1.2.0 becomes 1); pass 0.2 or 1 to choose yourself. It refuses when the latest version already has a number.
versions:archive builds the site, freezes the latest version's built docs into archive/v<id>/ and opens a new next. Links between docs pages are rewritten into the snapshot, assets move to _assets/, and pages get noindex so old versions don't compete with the latest in search results. --skip-build archives the dist/ you already have.

Commit archive/ and data/versions.json.

Never edit the archive by hand

Snapshots are built output. Fix an old version by rebuilding it from its release and archiving it again. Patch releases update the current docs in place rather than getting a version of their own.

URLs#

URL	Description
`/docs/...`	The latest version, rendered from pages/docs.
`/docs/v<id>/...`	An archived version, from archive/v<id>/. Also /docs/v<id>.md and each page's .md with the docs plugin.
`/docs/versions.json`	The manifest: every version with its path, release date, sitemap and the pages it has.

The version in development never reaches a URL: it is always served at /docs, and only archived versions get a /v<id> prefix. Links that must point across versions carry data-version-link, which archiving leaves alone.

Options#

Option	Description
`prefix`	Route prefix of the docs, the same as the docs plugin's. Default "/docs".
`file`	The versions file, relative to the project root. Default "data/versions.json".
`archive`	Where frozen versions are kept, relative to the project root. Default "archive".

The functions behind the commands are exported for release scripts of your own: nameVersion, startNext, archiveDocs, versionId, readVersionsFile and writeVersionsFile. This repository's bun run version:set uses them to name the docs version and set its package versions in one step.