docs: render the current version from git tags, and deploy on every merge

.github/workflows/deploy-docs.yml

@@ -2,13 +2,15 @@ name: Deploy docs
 
 on:
   push:
+    # Deliberately NO path filter on master. The published version now comes from git tags rather than from a literal in
+    # docs/, so a build's output can change without any watched path changing — a release would otherwise leave the site
+    # advertising the previous version until someone happened to touch a doc.
     branches:
       - master
-    paths:
-      - "docs/**"
-      - "bleep-site/**"
-      - "docs-snippets-from-tests/**"
-      - ".github/workflows/deploy-docs.yml"
+    # And a release is exactly that case: cutting `v1.0.0-M12` changes what every `$version:` example renders as, without
+    # moving master at all.
+    tags:
+      - "v*"
   pull_request:
     paths:
       - "docs/**"
@@ -31,6 +33,9 @@ jobs:
       - uses: actions/checkout@v7
         with:
           submodules: recursive
+          # The site reads the newest `v*` tag to render `$version:` in every example. The default depth-1 checkout
+          # fetches no tags at all, and scripts/latest-version.mjs fails the build rather than guessing a version.
+          fetch-depth: 0
 
       - uses: actions/setup-node@v7
         with:

bleep-site/docusaurus.config.js

@@ -2,11 +2,19 @@
 // Note: type annotations allow type checking and IDEs autocompletion
 
 import { themes as prismThemes } from "prism-react-renderer";
+import { latestBleepVersion } from "./scripts/latest-version.mjs";
+import remarkBleepVersion from "./scripts/remark-bleep-version.mjs";
+
+// Resolved once per build from git tags. Docs write `BLEEP_LATEST_VERSION` and get this substituted in, so a release is
+// published by tagging it and nothing in docs/ has to be edited. Exposed as a custom field too, for the React pages
+// under src/pages/ which are not MDX and so never reach the remark plugin.
+const bleepVersion = latestBleepVersion();
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
   title: "Bleep",
   tagline: "A Bleeping Fast Build Tool",
+  customFields: { bleepVersion },
   url: "https://bleep.build",
   baseUrl: "/",
   onBrokenLinks: "throw",
@@ -47,6 +55,7 @@ const config = {
         docs: {
           path: "../docs",
           sidebarPath: "./sidebars.js",
+          remarkPlugins: [[remarkBleepVersion, { version: bleepVersion }]],
         },
         theme: {
           customCss: "./src/css/custom.css",

bleep-site/scripts/latest-version.mjs

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+/**
+ * The newest released bleep version, derived from the repository's own git tags.
+ *
+ * Releases are cut by pushing a `v<version>` tag, so the tags ARE the release history and nothing else has to be kept in
+ * sync by hand. `--sort=-v:refname` is git's version sort, which orders `M10` above `M9` numerically (a plain lexical
+ * sort does not) and orders a final release above its own prereleases, so a future `v1.0.0` wins over `v1.0.0-M11`.
+ *
+ * Throws when no tag is found rather than guessing. The usual cause is a shallow clone: `actions/checkout` fetches no
+ * tags at depth 1, so any workflow calling this needs `fetch-depth: 0`. A guessed or stale version here would be
+ * published as documentation telling people to depend on a version that may not exist, which is worse than a failed
+ * build.
+ */
+export function latestBleepVersion() {
+  const stdout = execFileSync("git", ["tag", "-l", "v*", "--sort=-v:refname"], {
+    cwd: repoRoot,
+    encoding: "utf8",
+  });
+
+  const newest = stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)[0];
+
+  if (!newest) {
+    throw new Error(
+      `No 'v*' git tags found in ${repoRoot}, so the latest bleep version cannot be determined. ` +
+        `If this is CI, the checkout needs 'fetch-depth: 0' — tags are not fetched at depth 1.`,
+    );
+  }
+
+  return newest.replace(/^v/, "");
+}

bleep-site/scripts/remark-bleep-version.mjs

@@ -0,0 +1,42 @@
+/**
+ * The token documentation writes instead of a literal bleep version.
+ *
+ * Deliberately not a general "replace any version-shaped string" rewrite. Several pages refer to specific past releases
+ * on purpose ("the machine-wide accounting arrived after 1.0.0-M10"), and rewriting those to the current version would
+ * silently turn true statements into false ones. Only this explicit token is substituted.
+ */
+export const VERSION_PLACEHOLDER = "BLEEP_LATEST_VERSION";
+
+/** Node types whose `value` is rendered text a reader can see. `code` covers fenced blocks, which is where `$version:` lives. */
+const TEXTUAL_NODES = new Set(["code", "inlineCode", "text"]);
+
+/**
+ * Replaces {@link VERSION_PLACEHOLDER} with the newest released version, everywhere it appears in the docs.
+ *
+ * This runs as a remark plugin rather than as a build-time find-and-replace over the source files because the docs are
+ * checked in: rewriting them in place would mean a commit on every release, and a dirty working tree for anyone who
+ * built the site locally.
+ *
+ * MDX has no interpolation inside fenced code blocks, which is exactly where the version is needed, so operating on the
+ * parsed tree is the only option that reaches it.
+ */
+export default function remarkBleepVersion({ version }) {
+  if (!version) {
+    throw new Error("remark-bleep-version requires a 'version' option");
+  }
+
+  return (tree) => {
+    visit(tree);
+  };
+
+  function visit(node) {
+    if (TEXTUAL_NODES.has(node.type) && typeof node.value === "string") {
+      node.value = node.value.split(VERSION_PLACEHOLDER).join(version);
+    }
+    if (Array.isArray(node.children)) {
+      for (const child of node.children) {
+        visit(child);
+      }
+    }
+  }
+}

docs/compared-to-other-build-tools/gradle.mdx

@@ -61,7 +61,7 @@ tasks.test {
 
 ```yaml
 $schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
-$version: 1.0.0-M9
+$version: BLEEP_LATEST_VERSION
 
 projects:
   myapp:

docs/compared-to-other-build-tools/maven.mdx

@@ -72,7 +72,7 @@ The same single-module Java project, in `pom.xml` and in `bleep.yaml`:
 
 ```yaml
 $schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
-$version: 1.0.0-M9
+$version: BLEEP_LATEST_VERSION
 
 projects:
   myapp:

docs/compared-to-other-build-tools/mill.mdx

@@ -59,7 +59,7 @@ object mylib extends ScalaModule with PublishModule {
 
 ```yaml
 $schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
-$version: 1.0.0-M9
+$version: BLEEP_LATEST_VERSION
 
 projects:
   mylib:

docs/compared-to-other-build-tools/sbt.mdx

@@ -52,7 +52,7 @@ addSbtPlugin("com.github.sbt" % "sbt-ci-release" % "1.5.12")
 
 ```yaml
 $schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
-$version: 1.0.0-M9
+$version: BLEEP_LATEST_VERSION
 
 projects:
   mylib:

docs/compared-to-other-build-tools/scala-cli.mdx

@@ -39,7 +39,7 @@ The same thing in bleep:
 
 ```yaml
 $schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
-$version: 1.0.0-M9
+$version: BLEEP_LATEST_VERSION
 
 projects:
   myapp:

docs/tutorials/kotlin-with-ksp.mdx

@@ -33,7 +33,7 @@ Replace the generated `bleep.yaml` with:
 
 ```yaml
 $schema: https://raw.githubusercontent.com/oyvindberg/bleep/master/schema.json
-$version: 1.0.0-M9
+$version: BLEEP_LATEST_VERSION
 
 projects:
   myapp: