@zebradil/docs-kit 0.11.0 → 0.12.0

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.11.0" } }
+{ "private": true, "type": "module", "dependencies": { "@zebradil/docs-kit": "0.12.0" } }
 ```
 <!-- x-release-please-end -->
 
@@ -80,7 +80,7 @@ versions:
   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, and release pages carry a banner linking to the current docs and 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).
+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.
 
@@ -97,7 +97,7 @@ on:
 permissions: { contents: read, pages: write, id-token: write }
 jobs:
   docs:
-    uses: Zebradil/docs-kit/.github/workflows/docs.yml@v0.11.0
+    uses: Zebradil/docs-kit/.github/workflows/docs.yml@v0.12.0
 ```
 <!-- x-release-please-end -->
 
@@ -105,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 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.
+On every run it installs `docs/` with `npm ci`, runs `prebuild` (from the repository root) when set, 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:
 
@@ -114,6 +114,7 @@ Inputs, all optional:
 | `directory` | `docs` | Docs directory, relative to the repository root. |
 | `nix` | `false` | Install Nix first, for `build: nix build` and friends. |
 | `deploy` | `true` | Deploy on pushes to the default branch. |
+| `prebuild` | | Shell command run from the repository root before the CLI build, for generated files the site serves, such as `docs/public/demo/`. Release versions keep the `public/` of their tag, so they do not get these files. |
 
 Runs on `ubuntu-latest`, which already has Rust (cargo, rustup) and Go (default version linked into `/usr/bin`; a newer `go` line in `go.mod` makes Go download that toolchain itself); see the [runner image tool list](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md).
 

package/package.json

@@ -29,7 +29,7 @@
     "validate": "node schema/validate.mjs"
   },
   "dependencies": {
-    "@astrojs/starlight": "0.42.10",
+    "@astrojs/starlight": "0.42.11",
     "@fontsource-variable/fraunces": "5.3.0",
     "@fontsource-variable/instrument-sans": "5.3.0",
     "@fontsource-variable/jetbrains-mono": "5.3.0",
@@ -40,5 +40,5 @@
     "astro": "7.4.11",
     "yaml": "2.9.1"
   },
-  "version": "0.11.0"
+  "version": "0.12.0"
 }

package/packages/docs-kit/Banner.astro

@@ -3,17 +3,36 @@ import Default from '@astrojs/starlight/components/Banner.astro';
 import { root, version } from 'virtual:docs-kit/site';
 ---
 
-{
-  version && (
-    <div class="kit-version-banner" data-pagefind-ignore>
-      These docs are for {version}. <a href={root}>Read the current docs</a>.
-    </div>
-  )
-}
+{/* 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 {
+  .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);

package/packages/docs-kit/SiteTitle.astro

@@ -41,5 +41,6 @@ import { root, version } from 'virtual:docs-kit/site';
   kit-versions:not([hidden]) {
     display: flex;
     align-items: center;
+    margin-inline-start: 1rem;
   }
 </style>