@knitli/astro-docs-template 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -38,9 +38,9 @@
     "clean": "rm -rf dist",
     "deploy": "bun publish --tag latest",
     "prepack": "bun run build",
-    "test": "vitest run src/index.test.ts",
+    "test": "vitest run src/index.test.ts src/remarkPlugin.test.ts",
     "test:integration": "vitest run src/integration.test.ts",
-    "test:unit": "vitest run src/index.test.ts",
+    "test:unit": "vitest run src/index.test.ts src/remarkPlugin.test.ts",
     "test:watch": "vitest"
   },
   "dependencies": {

package/src/config.ts

@@ -497,7 +497,6 @@ export default async function createConfig(options: DocsTemplateOptions) {
           external: ["shiki", "shiki-esbuild"],
           output: {
             format: "es",
-            dir: `${rootDir}/dist/_astro/`,
             compact: true,
             interop: "esModule",
             experimentalMinChunkSize: 10000,
@@ -514,9 +513,6 @@ export default async function createConfig(options: DocsTemplateOptions) {
               objectShorthand: true,
               symbols: true,
             },
-            entryFileNames: "assets/[name]-[hash].js",
-            chunkFileNames: "assets/[name]-[hash].js",
-            assetFileNames: "assets/[name]-[hash][extname]",
           },
           treeshake: "smallest",
         },

package/src/remarkPlugin.test.ts

@@ -0,0 +1,207 @@
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Unit tests for `remarkVersion`.
+ *
+ * The plugin's only side effect is mutating an mdast tree, so the tests
+ * construct synthetic trees by hand instead of pulling in `remark-parse`
+ * / `remark-mdx` (no extra deps, no parser-version drift). The exact
+ * version string returned by `getVersion()` depends on the test
+ * environment's `git describe` output, so we assert structurally —
+ * confirming that the token was replaced with *something* version-like,
+ * not pinning a specific value.
+ */
+
+import type { Root, Text } from "mdast";
+import { describe, expect, it } from "vitest";
+import { remarkVersion } from "./remarkPlugin.js";
+
+// A version string is something like `0.4.5`, `0.4.5-dev`, `0.4.5-beta.1`,
+// a bare commit hash from `git describe --always`, or the `0.0.0-unknown`
+// fallback. We just want it to be non-empty and free of the placeholder.
+const VERSION_LIKE = /^[\w.+-]+$/;
+
+function applyPlugin(tree: Root): Root {
+  remarkVersion()(tree);
+  return tree;
+}
+
+// Synthetic node helpers. Cast through unknown so we can build mdast +
+// MDX shapes without importing `mdast-util-mdx-expression` types.
+function textNode(value: string): Text {
+  return { type: "text", value };
+}
+
+function mdxTextExpression(value: string): Text {
+  return {
+    type: "mdxTextExpression",
+    value,
+    data: { estree: { type: "Program", body: [] } },
+  } as unknown as Text;
+}
+
+function mdxFlowExpression(value: string): Text {
+  return {
+    type: "mdxFlowExpression",
+    value,
+    data: { estree: { type: "Program", body: [] } },
+  } as unknown as Text;
+}
+
+describe("remarkVersion", () => {
+  describe("plain text nodes (.md path)", () => {
+    it("replaces a single {{VERSION}} occurrence", () => {
+      const tree: Root = {
+        type: "root",
+        children: [
+          {
+            type: "paragraph",
+            children: [textNode("Version is {{VERSION}} today")],
+          },
+        ],
+      };
+
+      applyPlugin(tree);
+
+      const text = (tree.children[0] as { children: Text[] }).children[0];
+      expect(text.type).toBe("text");
+      expect(text.value).not.toContain("{{VERSION}}");
+      expect(text.value.startsWith("Version is ")).toBe(true);
+      expect(text.value.endsWith(" today")).toBe(true);
+      const replaced = text.value.slice("Version is ".length, -" today".length);
+      expect(replaced).toMatch(VERSION_LIKE);
+    });
+
+    it("replaces multiple occurrences in the same text node", () => {
+      const tree: Root = {
+        type: "root",
+        children: [
+          {
+            type: "paragraph",
+            children: [textNode("{{VERSION}} and {{VERSION}}")],
+          },
+        ],
+      };
+
+      applyPlugin(tree);
+
+      const text = (tree.children[0] as { children: Text[] }).children[0];
+      expect(text.value).not.toContain("{{VERSION}}");
+      const parts = text.value.split(" and ");
+      expect(parts).toHaveLength(2);
+      // Both replacements use the same cached version, so they must
+      // produce identical strings.
+      expect(parts[0]).toBe(parts[1]);
+      expect(parts[0]).toMatch(VERSION_LIKE);
+    });
+
+    it("leaves text nodes without the token untouched", () => {
+      const original = "no token here";
+      const tree: Root = {
+        type: "root",
+        children: [{ type: "paragraph", children: [textNode(original)] }],
+      };
+
+      applyPlugin(tree);
+
+      const text = (tree.children[0] as { children: Text[] }).children[0];
+      expect(text.value).toBe(original);
+    });
+  });
+
+  describe("MDX expression nodes (.mdx path)", () => {
+    it("mutates an mdxTextExpression with value '{VERSION}' into a text node", () => {
+      const tree: Root = {
+        type: "root",
+        children: [
+          {
+            type: "paragraph",
+            children: [textNode("v"), mdxTextExpression("{VERSION}")],
+          },
+        ],
+      };
+
+      applyPlugin(tree);
+
+      const para = tree.children[0] as {
+        children: Array<Text & { data?: unknown }>;
+      };
+      const node = para.children[1];
+      expect(node.type).toBe("text");
+      expect(node.value).toMatch(VERSION_LIKE);
+      // estree metadata must be cleared so the MDX serializer doesn't
+      // try to re-evaluate the (now-text) node as JavaScript.
+      expect(node.data).toBeUndefined();
+    });
+
+    it("mutates an mdxFlowExpression with value '{VERSION}' into a text node", () => {
+      const tree: Root = {
+        type: "root",
+        children: [mdxFlowExpression("{VERSION}")],
+      };
+
+      applyPlugin(tree);
+
+      const node = tree.children[0] as Text & { data?: unknown };
+      expect(node.type).toBe("text");
+      expect(node.value).toMatch(VERSION_LIKE);
+      expect(node.data).toBeUndefined();
+    });
+
+    it("tolerates whitespace inside the expression ('{ VERSION }')", () => {
+      const tree: Root = {
+        type: "root",
+        children: [mdxTextExpression("{ VERSION }")],
+      };
+
+      applyPlugin(tree);
+
+      const node = tree.children[0] as Text;
+      expect(node.type).toBe("text");
+      expect(node.value).toMatch(VERSION_LIKE);
+    });
+
+    it("leaves unrelated MDX expressions alone", () => {
+      const tree: Root = {
+        type: "root",
+        children: [
+          mdxTextExpression("{otherVar}"),
+          mdxTextExpression("{1 + 2}"),
+          mdxFlowExpression("{someComponent}"),
+        ],
+      };
+
+      applyPlugin(tree);
+
+      expect(tree.children[0].type).toBe("mdxTextExpression");
+      expect((tree.children[0] as { value: string }).value).toBe("{otherVar}");
+      expect(tree.children[1].type).toBe("mdxTextExpression");
+      expect((tree.children[1] as { value: string }).value).toBe("{1 + 2}");
+      expect(tree.children[2].type).toBe("mdxFlowExpression");
+      expect((tree.children[2] as { value: string }).value).toBe(
+        "{someComponent}",
+      );
+    });
+  });
+
+  describe("escaped form backwards-compat", () => {
+    it("still works when users escape the braces in .mdx", () => {
+      // After MDX parsing, `\{\{VERSION\}\}` becomes a plain text node
+      // with literal content `{{VERSION}}`. Pass 1 (the text-node visitor)
+      // should still substitute it, so any pre-fix workarounds keep
+      // rendering correctly after consumers upgrade.
+      const tree: Root = {
+        type: "root",
+        children: [{ type: "paragraph", children: [textNode("{{VERSION}}")] }],
+      };
+
+      applyPlugin(tree);
+
+      const text = (tree.children[0] as { children: Text[] }).children[0];
+      expect(text.value).not.toContain("{{VERSION}}");
+      expect(text.value).toMatch(VERSION_LIKE);
+    });
+  });
+});

package/src/remarkPlugin.ts

@@ -3,16 +3,42 @@
 // 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`.
+ * Remark plugin that replaces `{{VERSION}}` tokens in markdown / MDX
+ * content with the current version derived from `git describe`.
  *
  * Runs at build time — no runtime cost.
+ *
+ * Works in two passes so it functions identically in `.md` and `.mdx`:
+ *
+ *   1. Plain markdown text nodes: `{{VERSION}}` is a literal substring
+ *      in a `text` node and gets replaced directly. This covers all of
+ *      `.md` and any text in `.mdx` that isn't wrapped in JSX expression
+ *      delimiters.
+ *
+ *   2. MDX expression nodes: in `.mdx` files, MDX parses `{...}` as a
+ *      JavaScript expression delimiter at parse time, so `{{VERSION}}`
+ *      becomes an `mdxTextExpression` (inline) or `mdxFlowExpression`
+ *      (block) node whose `value` is the inner `{VERSION}` — and the
+ *      remark text visitor never sees the token. If left alone, MDX
+ *      would try to evaluate `{ VERSION }` as JS at render time and
+ *      throw `ReferenceError: VERSION is not defined`. We detect those
+ *      nodes and mutate them into plain `text` nodes carrying the
+ *      resolved version string, dropping the estree metadata so the
+ *      downstream serializer doesn't re-attempt evaluation.
  */
 
 import { execFileSync } from "node:child_process";
 import type { Root, Text } from "mdast";
+import type { Node } from "unist";
 import { visit } from "unist-util-visit";
 
+const VERSION_TOKEN = "{{VERSION}}";
+
+// MDX strips the outer `{` `}` expression delimiters, so the value of an
+// `mdxTextExpression` / `mdxFlowExpression` node holding `{{VERSION}}`
+// is the inner `{VERSION}` (with optional surrounding whitespace).
+const MDX_VERSION_EXPRESSION_RE = /^\s*\{\s*VERSION\s*\}\s*$/;
+
 let cachedVersion: string | undefined;
 
 function getVersion(): string {
@@ -50,9 +76,31 @@ export function remarkVersion(): (tree: Root) => void {
   return (tree: Root) => {
     const version = getVersion();
 
+    // Pass 1: plain markdown text nodes.
     visit(tree, "text", (node: Text) => {
-      if (node.value.includes("{{VERSION}}")) {
-        node.value = node.value.replaceAll("{{VERSION}}", version);
+      if (node.value.includes(VERSION_TOKEN)) {
+        node.value = node.value.replaceAll(VERSION_TOKEN, version);
+      }
+    });
+
+    // Pass 2: MDX expression nodes (only present in `.mdx` files).
+    // We use a structural cast because `mdxTextExpression` /
+    // `mdxFlowExpression` are defined in `mdast-util-mdx-expression`,
+    // not in `mdast`, and adding that as a direct dep just for type
+    // imports would bloat the dependency surface.
+    visit(tree, ["mdxTextExpression", "mdxFlowExpression"], (node: Node) => {
+      const expr = node as Node & {
+        value?: unknown;
+        type: string;
+        data?: unknown;
+      };
+      if (
+        typeof expr.value === "string" &&
+        MDX_VERSION_EXPRESSION_RE.test(expr.value)
+      ) {
+        expr.type = "text";
+        (expr as { value: string }).value = version;
+        if ("data" in expr) delete expr.data;
       }
     });
   };