@knitli/astro-docs-template 0.4.3 → 0.4.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -45,25 +45,26 @@
   },
   "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.9",
+    "postcss": "8.5.6",
     "postcss-nesting": "^14.0.0",
     "rehype-external-links": "^3.0.0",
     "sharp": "^0.34.5",
@@ -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

@@ -18,6 +18,8 @@ import { defineConfig, fontProviders } from "astro/config";
 import cloudflarePagesHeaders from "astro-cloudflare-pages-headers";
 import astroD2 from "astro-d2";
 import favicons from "astro-favicons";
+import type { PluginCreator } from "postcss";
+import type { pluginOptions } from "postcss-nesting";
 import rehypeExternalLinks from "rehype-external-links";
 import starlightAnnouncement from "starlight-announcement";
 import starlightChangelogs from "starlight-changelogs";
@@ -34,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"
@@ -48,6 +51,12 @@ function nonNullable<T>(value: T): value is NonNullable<T> {
   return value != null;
 }
 
+const postcssNesting = async (options?: { edition: "2021" | "2024-02" }) => {
+  // Dynamically import postcss-nesting to avoid bundling it in the template's node_modules
+  const { default: createPlugin } = await import("postcss-nesting");
+  return createPlugin(options) as unknown as PluginCreator<pluginOptions>;
+};
+
 // ── Defaults (defined before interface so `typeof` references work) ──
 
 export const {
@@ -396,7 +405,7 @@ const defaultHeadersConfig: OutgoingHttpHeaders = {
     "default-src 'self'; script-src 'self' 'unsafe-inline' static.cloudflareinsights.com zaraz.cloudflare.com; connect-src 'self' cloudflareinsights.com *.cloudflareinsights.com; img-src 'self' media.knitli.com data: avatars.githubusercontent.com ui-avatars.com media.knitli.com knitli.com; style-src 'self' 'unsafe-inline' fonts.googleapis.com; font-src 'self' fonts.gstatic.com; frame-ancestors 'none'",
 };
 
-export default function createConfig(options: DocsTemplateOptions) {
+export default async function createConfig(options: DocsTemplateOptions) {
   const {
     appName,
     description,
@@ -452,6 +461,7 @@ export default function createConfig(options: DocsTemplateOptions) {
           { content: { type: "text", value: " ↗" }, rel: ["nofollow"] },
         ],
       ],
+      remarkPlugins: [remarkVersion],
     },
     server: {
       headers: { ...defaultHeadersConfig, ...headersConfig },
@@ -464,6 +474,9 @@ export default function createConfig(options: DocsTemplateOptions) {
           allow: [searchForWorkspaceRoot(rootDir)],
         },
       },
+      optimizeDeps: {
+        exclude: [""],
+      },
       assetsInclude: [
         "src/*.webp",
         "src/*.png",
@@ -511,7 +524,11 @@ export default function createConfig(options: DocsTemplateOptions) {
       },
       css: {
         postcss: {
-          plugins: [require("postcss-nesting")()],
+          plugins: [
+            await postcssNesting({
+              edition: "2024-02",
+            }),
+          ],
         },
       },
     },

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);
+      }
+    });
+  };
+}