@knitli/astro-docs-template 0.2.4 → 0.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knitli/astro-docs-template",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
   "keywords": [
     "knitli",
@@ -64,10 +64,8 @@
     "starlight-scroll-to-top": ">=0.4.0",
     "starlight-sidebar-topics": ">=0.7.1",
     "starlight-tags": ">=0.4.0",
-    "vite-tsconfig-paths": "6.1.1"
-  },
-  "devDependencies": {
-    "@astrojs/check": "^0.9.6",
+    "vite-tsconfig-paths": "6.1.1",
+    "vite": "^7.0.0",
     "@astrojs/compiler-rs": "^0.1.4",
     "@biomejs/biome": "^2.4.2",
     "@knitli/tsconfig": "*",
@@ -77,6 +75,9 @@
     "lightningcss": "^1.30.2",
     "sharp": "^0.34.5",
     "svgo": "^4.0.0",
+    "@astrojs/check": "^0.9.6"
+  },
+  "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },

package/scaffolding/mise.toml

@@ -11,7 +11,7 @@ tools.bun = "latest"
 
 [tasks.gentypes]
 description = "Generate Cloudflare types for the project"
-run = "bunx wrangler types"
+run = "bunx wrangler types && bunx astro sync"
 tools.bun = "latest"
 tools.wrangler = "latest"
 depends = ["installdeps"]
@@ -63,3 +63,7 @@ tools.biome = "latest"
 description = "Fix linting issues using Biome"
 run = "biome check . --write --changed"
 tools.biome = "latest"
+
+[tasks.ufix]
+description = "Use unsafe fixes with Biome"
+run = "biome check . --write --changed --unsafe"

package/scaffolding/package.json

@@ -7,6 +7,7 @@
     "astro": "bunx astro",
     "prebuild": "bunx wrangler types; bunx astro sync",
     "build": "bunx astro build",
+    "predeploy": "bun run build",
     "deploy": "bun run build && bunx wrangler deploy",
     "dev": "bunx astro dev",
     "prepare": "test -f ./node_modules/bun/install.js && node ./node_modules/bun/install.js || true",
@@ -14,8 +15,10 @@
     "wrangler": "bunx wrangler"
   },
   "dependencies": {
+    "@astrojs/starlight": "^0.38.1",
     "@knitli/astro-docs-template": "latest",
-    "@knitli/docs-components": "latest"
+    "@knitli/docs-components": "latest",
+    "astro": "^6.1.1"
   },
   "devDependencies": {
     "@astrojs/check": "latest",

package/scaffolding/src/content.config.ts

@@ -1,7 +1,20 @@
 import { defineCollection } from "astro:content";
 import { docsLoader } from "@astrojs/starlight/loaders";
 import { docsSchema } from "@astrojs/starlight/schema";
+import { changelogsLoader } from "starlight-changelogs/loader";
 
 export const collections = {
   docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  changelogs: defineCollection({
+    loader: changelogsLoader([
+      {
+        provider: "keep-a-changelog",
+        base: "changelog",
+        changelog: "../../CHANGELOG.md",
+        pageSize: 10,
+        title: "Changelog",
+        pagefind: true,
+      },
+    ]),
+  }),
 };

package/scaffolding/wrangler.jsonc

@@ -9,7 +9,7 @@
     "directory": "./dist",
     "binding": "ASSETS",
     "html_handling": "auto-trailing-slash",
-    "not_found_handling": "404-errors",
+    "not_found_handling": "404-page",
     "run_worker_first": false
   },
   "observability": {

package/src/config.ts

@@ -52,8 +52,10 @@ export const {
   headlineLogoLight,
   variables,
   docsStyle,
-  faviconIco,
-  faviconSvg,
+  knitliFaviconIco,
+  knitliFaviconSvg,
+  codeweaverPrimary,
+  codeweaverReverse,
 } = DocsAssets;
 
 const shikiCfg = {
@@ -197,11 +199,12 @@ const getIntegrations = (options: IntegrationOptions) => {
     markdoc(),
     llmEnhancements({ llmsTxt: false }),
     mdx(),
+    starlightIconsIntegration(),
     favicons({
       name: `${appName} Docs by Knitli`,
       short_name: `${appName} Docs`,
       input: {
-        favicons: [faviconSvg],
+        favicons: [knitliFaviconSvg],
       },
     }),
     cloudflarePagesHeaders({}),
@@ -257,7 +260,6 @@ const get_plugins = (options: PluginOptions) => {
     starlightAnnouncement(),
     starlightChangelogs(),
     starlightHeadingBadges(),
-    starlightIconsIntegration(),
     starlightIconsPlugin(),
     starlightLinksValidator(),
     starlightPageActions({
@@ -317,6 +319,16 @@ const get_plugins = (options: PluginOptions) => {
   return [...filtered, ...overrides];
 };
 
+const defaultHeadersConfig: OutgoingHttpHeaders = {
+  "X-Frame-Options": "DENY",
+  "X-Content-Type-Options": "nosniff",
+  "Referrer-Policy": "strict-origin-when-cross-origin",
+  "Permissions-Policy":
+    "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()",
+  "content-security-policy":
+    "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) {
   const {
     appName,
@@ -334,7 +346,7 @@ export default function createConfig(options: DocsTemplateOptions) {
     integrationConfigs,
     unwantedIntegrations,
     unwantedPlugins,
-    headersConfig,
+    headersConfig = defaultHeadersConfig,
   } = options;
 
   // https://astro.build/config
@@ -378,7 +390,7 @@ export default function createConfig(options: DocsTemplateOptions) {
       ],
     },
     server: {
-      headers: headersConfig,
+      headers: { ...defaultHeadersConfig, ...headersConfig },
     },
     trailingSlash: "always",
     // Vite configuration for better bundling
@@ -478,10 +490,10 @@ export default function createConfig(options: DocsTemplateOptions) {
         pagefind: true,
         description: description,
         logo: {
-          dark: logoDark,
-          light: logoLight,
+          dark: is_codeweaver ? codeweaverReverse : logoDark,
+          light: is_codeweaver ? codeweaverPrimary : logoLight,
           alt: is_codeweaver ? "CodeWeaver Logo" : "Knitli Logo",
-          replacesTitle: true,
+          replacesTitle: !is_codeweaver,
         },
         editLink: {
           baseUrl: `https://github.com/knitli/${appName.toLowerCase()}/edit/main/docs-site/src`,

package/src/index.test.ts

@@ -2,18 +2,24 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
-import { existsSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   addPieces,
+  type InitOptions,
   initDocsTemplate,
   mergePackageJsonDeps,
-  normaliseDependencyVersion,
+  normalizeDependencyVersion,
   PIECE_NAMES,
   PIECES,
-  type InitOptions,
 } from "./index";
 
 // ── helpers ──────────────────────────────────────────────────────────────────
@@ -29,32 +35,32 @@ const BASE_OPTIONS: InitOptions = {
   workerName: "test-app-docs",
 };
 
-// ── normaliseDependencyVersion ────────────────────────────────────────────────
+// ── normalizeDependencyVersion ────────────────────────────────────────────────
 
-describe("normaliseDependencyVersion", () => {
+describe("normalizeDependencyVersion", () => {
   it("converts workspace:* to *", () => {
-    expect(normaliseDependencyVersion("workspace:*")).toBe("*");
+    expect(normalizeDependencyVersion("workspace:*")).toBe("*");
   });
 
   it("strips workspace: prefix from semver ranges, preserving the range", () => {
-    expect(normaliseDependencyVersion("workspace:^1.2.3")).toBe("^1.2.3");
-    expect(normaliseDependencyVersion("workspace:~1.0.0")).toBe("~1.0.0");
-    expect(normaliseDependencyVersion("workspace:>=2.0.0")).toBe(">=2.0.0");
+    expect(normalizeDependencyVersion("workspace:^1.2.3")).toBe("^1.2.3");
+    expect(normalizeDependencyVersion("workspace:~1.0.0")).toBe("~1.0.0");
+    expect(normalizeDependencyVersion("workspace:>=2.0.0")).toBe(">=2.0.0");
   });
 
   it("converts catalog:dev-common to latest", () => {
-    expect(normaliseDependencyVersion("catalog:dev-common")).toBe("latest");
+    expect(normalizeDependencyVersion("catalog:dev-common")).toBe("latest");
   });
 
   it("converts catalog:types to latest", () => {
-    expect(normaliseDependencyVersion("catalog:types")).toBe("latest");
+    expect(normalizeDependencyVersion("catalog:types")).toBe("latest");
   });
 
   it("leaves regular semver ranges unchanged", () => {
-    expect(normaliseDependencyVersion("^1.2.3")).toBe("^1.2.3");
-    expect(normaliseDependencyVersion("~2.0.0")).toBe("~2.0.0");
-    expect(normaliseDependencyVersion("latest")).toBe("latest");
-    expect(normaliseDependencyVersion("*")).toBe("*");
+    expect(normalizeDependencyVersion("^1.2.3")).toBe("^1.2.3");
+    expect(normalizeDependencyVersion("~2.0.0")).toBe("~2.0.0");
+    expect(normalizeDependencyVersion("latest")).toBe("latest");
+    expect(normalizeDependencyVersion("*")).toBe("*");
   });
 });
 
@@ -75,14 +81,16 @@ describe("mergePackageJsonDeps", () => {
     expect(result.dependencies?.astro).toBe("^5.0.0");
   });
 
-  it("normalises workspace:* in template deps", () => {
+  it("normalizes workspace:* in template deps", () => {
     const existing = { name: "x" };
-    const template = { dependencies: { "@knitli/astro-docs-template": "workspace:*" } };
+    const template = {
+      dependencies: { "@knitli/astro-docs-template": "workspace:*" },
+    };
     const result = mergePackageJsonDeps(existing, template);
     expect(result.dependencies?.["@knitli/astro-docs-template"]).toBe("*");
   });
 
-  it("normalises catalog:* in template devDependencies", () => {
+  it("normalizes catalog:* in template devDependencies", () => {
     const existing = { name: "x" };
     const template = { devDependencies: { typescript: "catalog:dev-common" } };
     const result = mergePackageJsonDeps(existing, template);
@@ -91,7 +99,12 @@ describe("mergePackageJsonDeps", () => {
 
   it("merges devDependencies", () => {
     const existing = { name: "x", devDependencies: { vitest: "^4.0.0" } };
-    const template = { devDependencies: { typescript: "catalog:dev-common", "@types/node": "catalog:types" } };
+    const template = {
+      devDependencies: {
+        typescript: "catalog:dev-common",
+        "@types/node": "catalog:types",
+      },
+    };
     const result = mergePackageJsonDeps(existing, template);
     expect(result.devDependencies).toEqual({
       vitest: "^4.0.0",
@@ -108,8 +121,18 @@ describe("mergePackageJsonDeps", () => {
   });
 
   it("does not touch name, version, scripts, or other fields", () => {
-    const existing = { name: "my-app", version: "1.2.3", scripts: { build: "tsc" }, private: true };
-    const template = { name: "template", version: "0.0.1", scripts: { dev: "astro dev" }, dependencies: { astro: "*" } };
+    const existing = {
+      name: "my-app",
+      version: "1.2.3",
+      scripts: { build: "tsc" },
+      private: true,
+    };
+    const template = {
+      name: "template",
+      version: "0.0.1",
+      scripts: { dev: "astro dev" },
+      dependencies: { astro: "*" },
+    };
     const result = mergePackageJsonDeps(existing, template);
     expect(result.name).toBe("my-app");
     expect(result.version).toBe("1.2.3");
@@ -159,7 +182,11 @@ describe("initDocsTemplate", () => {
 
   it("always clobbers existing files (init always overwrites, no flag needed)", () => {
     // Write an existing file that will be overwritten
-    writeFileSync(join(tmpDir, "tsconfig.json"), '{"compilerOptions":{}}', "utf-8");
+    writeFileSync(
+      join(tmpDir, "tsconfig.json"),
+      '{"compilerOptions":{}}',
+      "utf-8",
+    );
     const created = initDocsTemplate(tmpDir, BASE_OPTIONS);
     // tsconfig.json should have been re-created
     expect(created.some((f) => f.includes("tsconfig.json"))).toBe(true);
@@ -192,7 +219,10 @@ describe("addPieces", () => {
   });
 
   it("creates the requested file when it does not exist", () => {
-    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig"] });
+    const created = addPieces(tmpDir, {
+      ...BASE_OPTIONS,
+      pieces: ["tsconfig"],
+    });
     expect(created.length).toBe(1);
     expect(existsSync(join(tmpDir, "tsconfig.json"))).toBe(true);
   });
@@ -200,18 +230,29 @@ describe("addPieces", () => {
   it("skips an existing non-package.json file without --force", () => {
     // Pre-populate the tsconfig so it already exists
     writeFileSync(join(tmpDir, "tsconfig.json"), '{"existing":true}', "utf-8");
-    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig"] });
+    const created = addPieces(tmpDir, {
+      ...BASE_OPTIONS,
+      pieces: ["tsconfig"],
+    });
     expect(created.length).toBe(0);
     // Original content should be intact
-    const content = JSON.parse(readFileSync(join(tmpDir, "tsconfig.json"), "utf-8"));
+    const content = JSON.parse(
+      readFileSync(join(tmpDir, "tsconfig.json"), "utf-8"),
+    );
     expect(content.existing).toBe(true);
   });
 
   it("overwrites an existing non-package.json file with --force", () => {
     writeFileSync(join(tmpDir, "tsconfig.json"), '{"existing":true}', "utf-8");
-    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig"], force: true });
+    const created = addPieces(tmpDir, {
+      ...BASE_OPTIONS,
+      pieces: ["tsconfig"],
+      force: true,
+    });
     expect(created.length).toBe(1);
-    const content = JSON.parse(readFileSync(join(tmpDir, "tsconfig.json"), "utf-8"));
+    const content = JSON.parse(
+      readFileSync(join(tmpDir, "tsconfig.json"), "utf-8"),
+    );
     expect(content.existing).toBeUndefined();
   });
 
@@ -238,13 +279,19 @@ describe("addPieces", () => {
         private: true,
         dependencies: { express: "^4.0.0" },
       };
-      writeFileSync(join(tmpDir, "package.json"), JSON.stringify(existingPkg, null, 2), "utf-8");
+      writeFileSync(
+        join(tmpDir, "package.json"),
+        JSON.stringify(existingPkg, null, 2),
+        "utf-8",
+      );
 
       const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"] });
       // Should be modified (not 0 files)
       expect(created.length).toBe(1);
 
-      const merged = JSON.parse(readFileSync(join(tmpDir, "package.json"), "utf-8"));
+      const merged = JSON.parse(
+        readFileSync(join(tmpDir, "package.json"), "utf-8"),
+      );
       // Existing non-dep fields are preserved
       expect(merged.name).toBe("my-other-project");
       expect(merged.version).toBe("3.0.0");
@@ -256,11 +303,17 @@ describe("addPieces", () => {
       expect(merged.devDependencies?.["@astrojs/check"]).toBeDefined();
     });
 
-    it("normalises workspace:* references when merging", () => {
-      writeFileSync(join(tmpDir, "package.json"), '{"name":"x","dependencies":{}}', "utf-8");
+    it("normalizes workspace:* references when merging", () => {
+      writeFileSync(
+        join(tmpDir, "package.json"),
+        '{"name":"x","dependencies":{}}',
+        "utf-8",
+      );
       addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"] });
-      const merged = JSON.parse(readFileSync(join(tmpDir, "package.json"), "utf-8"));
-      // workspace:* should be normalised away
+      const merged = JSON.parse(
+        readFileSync(join(tmpDir, "package.json"), "utf-8"),
+      );
+      // workspace:* should be normalized away
       const allVersions = Object.values({
         ...merged.dependencies,
         ...merged.devDependencies,
@@ -270,18 +323,32 @@ describe("addPieces", () => {
     });
 
     it("throws a helpful error when existing package.json is not valid JSON", () => {
-      writeFileSync(join(tmpDir, "package.json"), "{ this is not valid json", "utf-8");
+      writeFileSync(
+        join(tmpDir, "package.json"),
+        "{ this is not valid json",
+        "utf-8",
+      );
       expect(() =>
         addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"] }),
       ).toThrow(/Failed to parse existing package\.json/);
     });
 
     it("replaces existing package.json wholesale with --force", () => {
-      const existingPkg = { name: "my-other-project", version: "3.0.0", scripts: { start: "node server.js" } };
-      writeFileSync(join(tmpDir, "package.json"), JSON.stringify(existingPkg, null, 2), "utf-8");
+      const existingPkg = {
+        name: "my-other-project",
+        version: "3.0.0",
+        scripts: { start: "node server.js" },
+      };
+      writeFileSync(
+        join(tmpDir, "package.json"),
+        JSON.stringify(existingPkg, null, 2),
+        "utf-8",
+      );
 
       addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["deps"], force: true });
-      const result = JSON.parse(readFileSync(join(tmpDir, "package.json"), "utf-8"));
+      const result = JSON.parse(
+        readFileSync(join(tmpDir, "package.json"), "utf-8"),
+      );
       // Should be the template's package.json content (with substitution applied)
       expect(result.name).toBe(BASE_OPTIONS.name);
     });
@@ -290,7 +357,10 @@ describe("addPieces", () => {
   // ── content piece ─────────────────────────────────────────────────────────
 
   it("copies directory pieces (starter-content)", () => {
-    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["starter-content"] });
+    const created = addPieces(tmpDir, {
+      ...BASE_OPTIONS,
+      pieces: ["starter-content"],
+    });
     expect(created.length).toBeGreaterThan(0);
     expect(existsSync(join(tmpDir, "src/content/docs"))).toBe(true);
   });
@@ -298,7 +368,10 @@ describe("addPieces", () => {
   // ── multiple pieces ───────────────────────────────────────────────────────
 
   it("can add multiple pieces at once", () => {
-    const created = addPieces(tmpDir, { ...BASE_OPTIONS, pieces: ["tsconfig", "styles"] });
+    const created = addPieces(tmpDir, {
+      ...BASE_OPTIONS,
+      pieces: ["tsconfig", "styles"],
+    });
     expect(existsSync(join(tmpDir, "tsconfig.json"))).toBe(true);
     expect(existsSync(join(tmpDir, "src/styles/custom.css"))).toBe(true);
     expect(created.length).toBe(2);

package/src/index.ts

@@ -166,7 +166,7 @@ function copyDirRecursive(
 }
 
 /**
- * Normalise a dependency version specifier so that workspace-protocol and
+ * Normalize a dependency version specifier so that workspace-protocol and
  * catalog entries from the Knitli monorepo become portable version strings
  * usable in any project.
  *
@@ -175,7 +175,7 @@ function copyDirRecursive(
  *   "catalog:something"  → "latest"
  *   anything else        → unchanged
  */
-export function normaliseDependencyVersion(version: string): string {
+export function normalizeDependencyVersion(version: string): string {
   if (version.startsWith("workspace:")) {
     const spec = version.slice("workspace:".length).trim();
     if (spec === "" || spec === "*") return "*";
@@ -195,7 +195,7 @@ type PackageJsonLike = {
 
 /**
  * Merge the `dependencies`, `devDependencies`, and `peerDependencies` from
- * `templatePkg` into `existingPkg`, normalising any monorepo-specific version
+ * `templatePkg` into `existingPkg`, normalizing any monorepo-specific version
  * specifiers so the result is portable.  Template entries take precedence over
  * existing entries for the same package name.
  *
@@ -215,11 +215,11 @@ export function mergePackageJsonDeps(
   for (const field of depFields) {
     const templateDeps = templatePkg[field];
     if (!templateDeps || Object.keys(templateDeps).length === 0) continue;
-    const normalised: PackageJsonDeps = {};
+    const normalized: PackageJsonDeps = {};
     for (const [pkg, version] of Object.entries(templateDeps)) {
-      normalised[pkg] = normaliseDependencyVersion(version);
+      normalized[pkg] = normalizeDependencyVersion(version);
     }
-    result[field] = { ...(existingPkg[field] ?? {}), ...normalised };
+    result[field] = { ...(existingPkg[field] ?? {}), ...normalized };
   }
   return result;
 }
@@ -231,10 +231,10 @@ export function mergePackageJsonDeps(
  *   (with placeholder substitution).
  * - If `force` is set, the file is overwritten wholesale.
  * - Otherwise the `dependencies`, `devDependencies`, and `peerDependencies`
- *   from the template are merged into the existing file, normalising any
+ *   from the template are merged into the existing file, normalizing any
  *   workspace-protocol / catalog version specifiers to portable equivalents.
  *
- * **Note**: the merged file is re-serialised with 2-space indentation using
+ * **Note**: the merged file is re-serialized with 2-space indentation using
  * `JSON.stringify`. Any bespoke formatting or key ordering in the original
  * file will not be preserved.
  */
@@ -258,7 +258,9 @@ function mergeOrCopyPackageJson(
 
   let existingPkg: PackageJsonLike;
   try {
-    existingPkg = JSON.parse(readFileSync(destPath, "utf-8")) as PackageJsonLike;
+    existingPkg = JSON.parse(
+      readFileSync(destPath, "utf-8"),
+    ) as PackageJsonLike;
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     throw new Error(