@knitli/astro-docs-template 0.4.4 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -45,23 +45,24 @@
   },
   "dependencies": {
     "@astrojs/check": "^0.9.6",
-    "@astrojs/cloudflare": "^13.1.7",
+    "@astrojs/cloudflare": "^13.1.8",
     "@astrojs/compiler-rs": "^0.1.6",
     "@astrojs/markdoc": "^1.0.0",
     "@astrojs/mdx": "^5.0.3",
     "@astrojs/sitemap": "^3.7.2",
-    "@astrojs/starlight": "^0.38.2",
+    "@astrojs/starlight": "^0.38.3",
     "@biomejs/biome": "^2.4.2",
     "@knitli/docs-components": "*",
     "@knitli/tsconfig": "*",
-    "@nuasite/llm-enhancements": "^0.19.1",
+    "@nuasite/llm-enhancements": "^0.23.0",
     "@types/bun": "^1.3.4",
-    "@types/node": "^24.0.2",
-    "astro": "^6.1.4",
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^24.12.2",
+    "astro": "^6.1.5",
     "astro-cloudflare-pages-headers": "^1.7.7",
     "astro-d2": "^0.10.0",
     "astro-favicons": "3.1.6",
-    "bun": "^1.3.9",
+    "bun": "^1.3.11",
     "lightningcss": "^1.30.2",
     "postcss": "8.5.6",
     "postcss-nesting": "^14.0.0",
@@ -78,7 +79,8 @@
     "starlight-sidebar-topics": ">=0.7.1",
     "starlight-tags": ">=0.4.0",
     "svgo": "^4.0.0",
-    "vite": "^7.3.1",
+    "unist-util-visit": "^5.1.0",
+    "vite": "^7.3.2",
     "vite-tsconfig-paths": "6.1.1"
   },
   "devDependencies": {

package/src/config.ts

@@ -36,6 +36,7 @@ import starlightSidebarTopics from "starlight-sidebar-topics";
 import starlightTags from "starlight-tags";
 import { searchForWorkspaceRoot } from "vite";
 import viteTsconfigPaths from "vite-tsconfig-paths";
+import { remarkVersion } from "./remarkPlugin.js";
 
 type defaultIntegration =
   | "sitemap"
@@ -460,6 +461,7 @@ export default async function createConfig(options: DocsTemplateOptions) {
           { content: { type: "text", value: " ↗" }, rel: ["nofollow"] },
         ],
       ],
+      remarkPlugins: [remarkVersion],
     },
     server: {
       headers: { ...defaultHeadersConfig, ...headersConfig },
@@ -472,6 +474,9 @@ export default async function createConfig(options: DocsTemplateOptions) {
           allow: [searchForWorkspaceRoot(rootDir)],
         },
       },
+      optimizeDeps: {
+        exclude: [""],
+      },
       assetsInclude: [
         "src/*.webp",
         "src/*.png",

package/src/remarkPlugin.ts

@@ -0,0 +1,59 @@
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+/**
+ * Remark plugin that replaces {{VERSION}} tokens in markdown content
+ * with the current version derived from `git describe`.
+ *
+ * Runs at build time — no runtime cost.
+ */
+
+import { execFileSync } from "node:child_process";
+import type { Root, Text } from "mdast";
+import { visit } from "unist-util-visit";
+
+let cachedVersion: string | undefined;
+
+function getVersion(): string {
+  if (cachedVersion !== undefined) return cachedVersion;
+
+  try {
+    const raw = execFileSync("git", ["describe", "--tags", "--always"], {
+      encoding: "utf-8",
+      timeout: 5000,
+    }).trim();
+
+    // Convert git describe output to clean version:
+    //   v0.2.0                        -> 0.2.0
+    //   v0.2.0-3-gabcdef              -> 0.2.0-dev
+    //   v0.1.0-alpha.5-103-gabcdef    -> 0.1.0-dev
+    //   v0.2.0-beta.1                 -> 0.2.0-beta.1
+    const match = raw.match(
+      /^v?(\d+\.\d+\.\d+)(?:-[a-z]+\.\d+)?(?:-(\d+)-g[a-f0-9]+)?$/,
+    );
+    if (match) {
+      const baseVersion = match[1];
+      const commitDistance = match[2];
+      cachedVersion = commitDistance ? `${baseVersion}-dev` : baseVersion;
+    } else {
+      cachedVersion = raw.replace(/^v/, "");
+    }
+  } catch {
+    cachedVersion = "0.0.0-unknown";
+  }
+
+  return cachedVersion || "0.0.0-unknown";
+}
+
+export function remarkVersion(): (tree: Root) => void {
+  return (tree: Root) => {
+    const version = getVersion();
+
+    visit(tree, "text", (node: Text) => {
+      if (node.value.includes("{{VERSION}}")) {
+        node.value = node.value.replaceAll("{{VERSION}}", version);
+      }
+    });
+  };
+}