@zebradil/docs-kit 0.10.0 → 0.11.1

package/README.md

@@ -44,7 +44,7 @@ The repository root is the npm package [`@zebradil/docs-kit`](https://www.npmjs.
 <!-- x-release-please-start-version -->
 ```jsonc
 // package.json
-{ "private": true, "type": "module", "dependencies": { "@zebradil/docs-kit": "0.10.0" } }
+{ "private": true, "type": "module", "dependencies": { "@zebradil/docs-kit": "0.11.1" } }
 ```
 <!-- x-release-please-end -->
 
@@ -71,6 +71,17 @@ analytics:
     data-website-id: 00000000-0000-0000-0000-000000000000
 ```
 
+To publish the docs of past releases next to the current ones, set `versions:` in `site.yaml`:
+
+```yaml
+versions:
+  minors: 3     # the 3 newest minor versions
+  majors: 3     # the newest minor of each of the 3 newest majors; below 1.0 each minor counts as a major
+  pin: [v1.4]   # always, e.g. a long-term support line
+```
+
+The default branch stays at the site root. Each selected minor version is rebuilt from its newest patch tag `vX.Y.Z` with the current kit at `/vX.Y/`, from the tag's `src/content/docs`, `src/assets` and `public/`, with `site.yaml` from the default branch. A version switcher appears in the header and marks the newest release, a banner on every other version, the default branch's included, links to the latest release, and release pages are kept out of search engines. Links between pages stay within a version only when they are relative. The workflow builds the versions only when it deploys; a release that no longer builds is skipped with a warning. To try it locally, run `npx astro build && npx --no-install docs-kit-versions` from `docs/` and serve `dist/`. See [ADR 0008](docs/adr/0008-versioned-docs-from-release-tags.md).
+
 For coding agents and LLMs, every site serves [`/llms.txt`](https://llmstxt.org), an index of all pages, and `/llms-full.txt`, all pages in one file. Each page's Markdown source is also served at its URL with `.md` appended (`/guides/configure/` → `/guides/configure.md`), with relative links made absolute. GitHub Pages cannot vary a response on the `Accept` header, so the `.md` URLs are the only Markdown route.
 
 ### Publishing with GitHub Actions
@@ -86,7 +97,7 @@ on:
 permissions: { contents: read, pages: write, id-token: write }
 jobs:
   docs:
-    uses: Zebradil/docs-kit/.github/workflows/docs.yml@v0.10.0
+    uses: Zebradil/docs-kit/.github/workflows/docs.yml@v0.11.1
 ```
 <!-- x-release-please-end -->
 
@@ -94,7 +105,7 @@ Keep `uses:` on its own indented line: Renovate's github-actions manager finds r
 
 The caller must grant `pages: write` and `id-token: write`: a called workflow can only narrow the caller's token permissions, never widen them, and the deploy job needs both.
 
-On every run it installs `docs/` with `npm ci`, builds the CLI with `reference.cli.build` (run from the repository root) when set, regenerates the CLI reference with `help2md` into `docs/src/content/docs/reference/cli`, and builds the site with `npx astro build` (which validates `site.yaml`). On a pull request it fails if the regenerated reference differs from the committed one and prints the diff. On a push to the default branch it deploys `docs/dist` to GitHub Pages.
+On every run it installs `docs/` with `npm ci`, builds the CLI with `reference.cli.build` (run from the repository root) when set, regenerates the CLI reference with `help2md` into `docs/src/content/docs/reference/cli`, and builds the site with `npx astro build` (which validates `site.yaml`). On a pull request it fails if the regenerated reference differs from the committed one and prints the diff. On a push to the default branch it builds the release versions when `versions:` is set and deploys `docs/dist` to GitHub Pages. A tag pushed with a workflow's `GITHUB_TOKEN` triggers no other workflow, so a new release shows up with the next deploy; to publish it at once, run the docs workflow on the default branch after the tag exists, for example from the release job.
 
 Inputs, all optional:
 

package/package.json

@@ -14,7 +14,8 @@
     "./content": "./packages/docs-kit/content.mjs"
   },
   "bin": {
-    "help2md": "refgen/help2md.mjs"
+    "help2md": "refgen/help2md.mjs",
+    "docs-kit-versions": "packages/docs-kit/versions.mjs"
   },
   "files": [
     "packages/docs-kit",
@@ -36,8 +37,8 @@
     "@fontsource/ibm-plex-mono": "5.3.0",
     "@fontsource/outfit": "5.3.0",
     "ajv": "8.20.0",
-    "astro": "7.4.7",
+    "astro": "7.4.11",
     "yaml": "2.9.1"
   },
-  "version": "0.10.0"
+  "version": "0.11.1"
 }

package/packages/docs-kit/Banner.astro

@@ -0,0 +1,44 @@
+---
+import Default from '@astrojs/starlight/components/Banner.astro';
+import { root, version } from 'virtual:docs-kit/site';
+---
+
+{/* Filled from versions.json at runtime: which release is the latest changes after a release's docs are built. */}
+<kit-version-banner class="kit-version-banner" data-root={root} data-version={version} data-pagefind-ignore hidden>
+  These docs are for <span></span>. <a>Read the docs of the latest release</a>.
+</kit-version-banner>
+<Default />
+
+<script>
+  customElements.define(
+    'kit-version-banner',
+    class extends HTMLElement {
+      async connectedCallback() {
+        const { root, version } = this.dataset as { root: string; version: string };
+        const response = await fetch(`${root}versions.json`).catch(() => undefined);
+        if (!response?.ok) return;
+        const versions: { name: string; path: string; latest?: true }[] = await response.json();
+        const latest = versions.find((v) => v.latest);
+        const current = version && `${version}/`;
+        if (!latest || latest.path === current) return;
+        const branch = versions.find((v) => v.path === '')?.name;
+        this.querySelector('span')!.textContent = version || `the development version (${branch})`;
+        this.querySelector('a')!.href = root + latest.path;
+        this.hidden = false;
+      }
+    },
+  );
+</script>
+
+<style>
+  .kit-version-banner:not([hidden]) {
+    display: block;
+    padding: var(--sl-nav-pad-y) var(--sl-nav-pad-x);
+    background-color: var(--sl-color-bg-accent);
+    color: var(--sl-color-text-invert);
+    text-align: center;
+  }
+  .kit-version-banner a {
+    color: inherit;
+  }
+</style>

package/packages/docs-kit/SiteTitle.astro

@@ -0,0 +1,46 @@
+---
+import Default from '@astrojs/starlight/components/SiteTitle.astro';
+import Select from '@astrojs/starlight/components/Select.astro';
+import { root, version } from 'virtual:docs-kit/site';
+---
+
+<Default />
+{/* Filled from versions.json at runtime, so the docs of a past release list releases made after it. */}
+<kit-versions data-root={root} data-version={version} hidden>
+  <Select icon="open-book" label="Docs version" options={[]} width="auto" />
+</kit-versions>
+
+<script>
+  customElements.define(
+    'kit-versions',
+    class extends HTMLElement {
+      async connectedCallback() {
+        const { root, version } = this.dataset as { root: string; version: string };
+        const select = this.querySelector('select')!;
+        const response = await fetch(`${root}versions.json`).catch(() => undefined);
+        if (!response?.ok) return;
+        const versions: { name: string; path: string; latest?: true }[] = await response.json();
+        const current = version && `${version}/`;
+        // The same page in another version: the URL path below the current version's base.
+        const page = location.pathname.slice(root.length + current.length);
+        for (const { name, path, latest } of versions) {
+          select.add(new Option(latest ? `${name} (latest release)` : name, path, false, path === current));
+        }
+        select.addEventListener('change', async () => {
+          const target = root + select.value;
+          const exists = await fetch(target + page, { method: 'HEAD' }).then((r) => r.ok, () => false);
+          location.href = exists ? target + page : target;
+        });
+        this.hidden = false;
+      }
+    },
+  );
+</script>
+
+<style>
+  kit-versions:not([hidden]) {
+    display: flex;
+    align-items: center;
+    margin-inline-start: 1rem;
+  }
+</style>

package/packages/docs-kit/index.mjs

@@ -16,7 +16,11 @@ export default function docsKit({ site: sitePath = 'site.yaml' } = {}) {
   // Hosting is GitHub Pages per repo: https://github.com/<owner>/<repo> is served at https://<owner>.github.io/<repo>,
   // or at the root of its custom domain.
   const [owner, repo] = new URL(site.repo).pathname.split('/').filter(Boolean);
-  const base = site.domain ? '' : `/${repo}`;
+  const root = site.domain ? '' : `/${repo}`;
+  // Set by docs-kit-versions when it builds a release's docs into <root>/<version>/.
+  const version = process.env.DOCS_KIT_VERSION ?? '';
+  if (!/^[\w.-]*$/.test(version)) throw new Error(`DOCS_KIT_VERSION '${version}' is not a path segment`);
+  const base = version ? `${root}/${version}` : root;
 
   // Starlight links public/favicon.svg itself; these are linked only when the project ships them.
   const icons = [
@@ -25,11 +29,13 @@ export default function docsKit({ site: sitePath = 'site.yaml' } = {}) {
   ]
     .filter(([file]) => existsSync(`public/${file}`))
     .map(([file, attrs]) => ({ tag: 'link', attrs: { ...attrs, href: `${base}/${file}` } }));
+  // A release's docs stay readable but out of search results, which should point at the current docs.
+  const noindex = version ? [{ tag: 'meta', attrs: { name: 'robots', content: 'noindex' } }] : [];
 
   return defineConfig({
     site: site.domain ? `https://${site.domain}` : `https://${owner.toLowerCase()}.github.io`,
     base: base || '/',
-    vite: { plugins: [siteModule(site)] },
+    vite: { plugins: [siteModule(site, { version, root: `${root}/` })] },
     integrations: [
       starlight({
         title: site.name,
@@ -37,12 +43,15 @@ export default function docsKit({ site: sitePath = 'site.yaml' } = {}) {
         logo: site.logo && (site.logo.dark ? { light: site.logo.light, dark: site.logo.dark } : { src: site.logo.light }),
         head: [
           ...icons,
+          ...noindex,
           ...(site.analytics
             ? [{ tag: 'script', attrs: { src: site.analytics.script, defer: true, ...site.analytics.attributes } }]
             : []),
         ],
         social: [{ icon: 'github', label: 'GitHub', href: site.repo }],
-        editLink: { baseUrl: `${site.repo}/edit/main/docs/` },
+        // A release's pages live in a tag, which GitHub cannot edit.
+        editLink: version ? {} : { baseUrl: `${site.repo}/edit/main/docs/` },
+        components: site.versions ? { SiteTitle: kitPath('SiteTitle.astro'), Banner: kitPath('Banner.astro') } : {},
         customCss: [kitPath('layout.css'), kitPath(`themes/${site.theme ?? 'default'}.css`)],
         sidebar: [
           { label: 'Getting started', slug: 'getting-started' },
@@ -66,12 +75,20 @@ export default function docsKit({ site: sitePath = 'site.yaml' } = {}) {
   });
 }
 
-/** Exposes the validated site.yaml to Landing.astro as `virtual:docs-kit/site`. */
-function siteModule(site) {
+/**
+ * Exposes the validated site.yaml to the kit's components as `virtual:docs-kit/site`, with the docs version being built
+ * ('' for the default branch) and the site root URL path, where versions.json lives.
+ */
+function siteModule(site, { version, root }) {
   const id = 'virtual:docs-kit/site';
+  const code = [
+    `export default ${JSON.stringify(site)};`,
+    `export const version = ${JSON.stringify(version)};`,
+    `export const root = ${JSON.stringify(root)};`,
+  ].join('\n');
   return {
     name: 'docs-kit-site',
     resolveId: (source) => (source === id ? `\0${id}` : undefined),
-    load: (resolved) => (resolved === `\0${id}` ? `export default ${JSON.stringify(site)};` : undefined),
+    load: (resolved) => (resolved === `\0${id}` ? code : undefined),
   };
 }

package/packages/docs-kit/kit.test.mjs

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { test } from 'node:test';
 import { fileURLToPath } from 'node:url';
 import docsKit from './index.mjs';
+import { minorVersions, selectVersions } from './versions.mjs';
 
 const path = (p) => fileURLToPath(new URL(p, import.meta.url));
 
@@ -43,3 +44,31 @@ test('accepts analytics with data-* attributes only', () => {
 test('rejects an invalid site.yaml with readable errors', () => {
   assert.throws(() => docsKit({ site: path('../../schema/testdata/broken.yaml') }), /must be one of: default, mono, porridge/);
 });
+
+test('serves a release version below the site root', (t) => {
+  t.after(() => delete process.env.DOCS_KIT_VERSION);
+  process.env.DOCS_KIT_VERSION = 'v1.2';
+  const config = docsKit({ site: path('../../examples/site.yaml') });
+  assert.equal(config.base, '/kasha/v1.2');
+  process.env.DOCS_KIT_VERSION = '../x';
+  assert.throws(() => docsKit({ site: path('../../examples/site.yaml') }), /not a path segment/);
+});
+
+test('picks the newest patch of each minor version, newest minor first', () => {
+  const tags = ['v1.2.0', 'v1.10.0', 'v1.2.3', 'v1.2.10', 'v2.0.0-rc.1', 'v0.9.1', 'docs-v3.0.0', 'v1.10.1', ''];
+  assert.deepEqual(minorVersions(tags), [
+    { name: 'v1.10', tag: 'v1.10.1', line: '1' },
+    { name: 'v1.2', tag: 'v1.2.10', line: '1' },
+    { name: 'v0.9', tag: 'v0.9.1', line: '0.9' },
+  ]);
+});
+
+test('selects the newest minors, the newest minor of each newest major, and pinned ones', () => {
+  const tags = ['v3.0.0', 'v2.5.0', 'v2.4.0', 'v2.3.0', 'v1.9.0', 'v1.8.0', 'v0.4.0', 'v0.3.0'];
+  const names = (options) => selectVersions(minorVersions(tags), options).map((v) => v.name);
+  assert.deepEqual(names({ majors: 3, minors: 3 }), ['v3.0', 'v2.5', 'v2.4', 'v1.9']);
+  assert.deepEqual(names({ majors: 0, minors: 1, pin: ['v1.8', 'v9.9'] }), ['v3.0', 'v1.8']);
+  // Below 1.0 each minor is its own release line.
+  assert.deepEqual(names({ majors: 5, minors: 0 }), ['v3.0', 'v2.5', 'v1.9', 'v0.4', 'v0.3']);
+  assert.deepEqual(names({}), ['v3.0', 'v2.5', 'v2.4', 'v1.9']);
+});

package/packages/docs-kit/versions.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Builds the docs of past releases next to the default branch's site in dist/: the newest patch tag (vX.Y.Z) of each
+// minor version that `versions:` in site.yaml selects, at dist/vX.Y/, and the list of all of them in dist/versions.json.
+// Each release's pages, assets and public files come from its tag; site.yaml, dependencies and the kit come from the
+// working tree, so every version is built with the current kit and theme.
+// Usage, from the docs directory after `astro build`: docs-kit-versions [--default-branch main]
+import { execFileSync, spawnSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { parse } from 'yaml';
+
+/**
+ * Release tags grouped by minor version, newest first, each with its newest patch and its release line: the major
+ * version, or `0.<minor>` below 1.0, where semver lets every minor break. Pre-releases are skipped.
+ */
+export function minorVersions(tags) {
+  const newest = new Map();
+  for (const tag of tags) {
+    const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
+    if (!match) continue;
+    const [major, minor, patch] = match.slice(1).map(Number);
+    const name = `v${major}.${minor}`;
+    if (!newest.has(name) || newest.get(name).patch < patch) newest.set(name, { name, tag, major, minor, patch });
+  }
+  return [...newest.values()]
+    .sort((a, b) => b.major - a.major || b.minor - a.minor)
+    .map(({ name, tag, major, minor }) => ({ name, tag, line: major ? `${major}` : `0.${minor}` }));
+}
+
+/**
+ * The minor versions to publish, newest first: the `minors` newest, the newest of each of the `majors` newest release
+ * lines, and the pinned ones.
+ */
+export function selectVersions(candidates, { majors = 3, minors = 3, pin = [] } = {}) {
+  const lines = [...new Set(candidates.map((c) => c.line))].slice(0, majors);
+  const newestOfLine = lines.map((line) => candidates.find((c) => c.line === line));
+  return candidates.filter((c, i) => i < minors || newestOfLine.includes(c) || pin.includes(c.name));
+}
+
+// Copied from a tag into the build: content replaces the working tree's, the others are laid over it so that files
+// site.yaml names (logo, art) stay present.
+const fromTag = ['src/content/docs', 'src/assets', 'public'];
+const skipped = /^(node_modules|dist|\.astro)(\/|$)/;
+
+function main() {
+  const { values } = parseArgs({ options: { 'default-branch': { type: 'string', default: 'main' } } });
+  const site = parse(readFileSync('site.yaml', 'utf8'));
+  if (!site.versions) throw new Error('site.yaml has no `versions:`; nothing to build');
+
+  const git = (...args) => execFileSync('git', args, { encoding: 'utf8' });
+  // `<tag>:./<path>` resolves the path against the working directory, wherever the docs directory is in the repo.
+  const has = (tag, path) => spawnSync('git', ['cat-file', '-e', `${tag}:./${path}`]).status === 0;
+  const candidates = minorVersions(git('tag', '--list', 'v*').split('\n')).filter(({ tag }) => has(tag, fromTag[0]));
+  for (const name of (site.versions.pin ?? []).filter((n) => !candidates.some((c) => c.name === n))) {
+    console.log(`::warning::Pinned docs version ${name} has no vX.Y.Z tag with ${fromTag[0]}`);
+  }
+
+  const built = [];
+  for (const { name, tag } of selectVersions(candidates, site.versions)) {
+    const out = resolve('dist', name);
+    // Inside the docs directory, so the build finds node_modules by walking up; a symlink confuses Astro's paths.
+    mkdirSync('.astro', { recursive: true });
+    const work = mkdtempSync(resolve('.astro/version-'));
+    try {
+      cpSync('.', work, { recursive: true, filter: (src) => !skipped.test(relative('.', src)) });
+      rmSync(join(work, fromTag[0]), { recursive: true });
+      // Pathspecs are relative to the working directory, and so are the archived paths.
+      const archive = execFileSync('git', ['archive', tag, '--', ...fromTag.filter((p) => has(tag, p))], {
+        maxBuffer: 1 << 30,
+      });
+      execFileSync('tar', ['-x', '-C', work], { input: archive });
+      console.log(`Building ${name} from ${tag}`);
+      const astro = resolve('node_modules/.bin/astro');
+      const result = spawnSync(astro, ['build', '--outDir', out], {
+        cwd: work,
+        env: { ...process.env, DOCS_KIT_VERSION: name },
+        stdio: 'inherit',
+      });
+      if (result.status !== 0) throw new Error(`astro build exited with ${result.status ?? result.signal}`);
+      built.push(name);
+    } catch (error) {
+      // One release that no longer builds with the current kit must not block publishing the others.
+      console.log(`::warning::Skipped the ${name} docs (${tag}): ${error.message}`);
+      rmSync(out, { recursive: true, force: true });
+    } finally {
+      rmSync(work, { recursive: true, force: true });
+    }
+  }
+
+  const latest = candidates[0]?.name;
+  const versions = [
+    { name: values['default-branch'], path: '' },
+    ...built.map((name) => ({ name, path: `${name}/`, ...(name === latest && { latest: true }) })),
+  ];
+  mkdirSync('dist', { recursive: true });
+  writeFileSync('dist/versions.json', `${JSON.stringify(versions, null, 2)}\n`);
+  console.log(`Wrote dist/versions.json: ${versions.map((v) => v.name).join(', ')}`);
+}
+
+// npx runs this through a symlink in node_modules/.bin; tests import it for minorVersions.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/schema/site.schema.json

@@ -461,6 +461,32 @@
         }
       }
     },
+    "versions": {
+      "description": "Publishes the docs of past releases next to the default branch's, which stay at the site root. Each selected minor version is served at <site>/vX.Y/ from its newest patch tag (vX.Y.Z), with a version switcher in the header that marks the newest release. A release's pages, src/assets and public/ come from its tag; site.yaml and the kit come from the default branch, so every version gets the current theme. Pre-releases and tags without the docs directory's src/content/docs are skipped.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "minors": {
+          "description": "Publishes the newest this many minor versions.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 20,
+          "default": 3
+        },
+        "majors": {
+          "description": "Publishes the newest minor version of each of the newest this many major versions. Below 1.0 every minor version counts as a major one, since semver lets it break.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 20,
+          "default": 3
+        },
+        "pin": {
+          "description": "Minor versions published whatever 'minors' and 'majors' select, e.g. a long-term support line.",
+          "type": "array",
+          "items": { "type": "string", "pattern": "^v\\d+\\.\\d+$" }
+        }
+      }
+    },
     "reference": {
       "description": "How refgen produces the generated pages under reference/. Omit when the project has no CLI.",
       "type": "object",