@knitli/astro-docs-template 0.1.0

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@knitli/astro-docs-template",
+  "version": "0.1.0",
+  "description": "Opinionated Astro + Starlight docs site template with Knitli branding",
+  "keywords": [
+    "knitli",
+    "astro",
+    "starlight",
+    "documentation",
+    "template"
+  ],
+  "homepage": "https://docs.knitli.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/knitli/knitli-site.git",
+    "directory": "packages/shared/astro-docs-template"
+  },
+  "license": "(MIT OR Apache-2.0) AND LicenseRef-KnitliProprietary",
+  "author": "Knitli Inc.",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./config": "./src/config.ts"
+  },
+  "files": [
+    "src",
+    "scaffolding",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "bunx tsc --noCheck",
+    "prepublishOnly": "bun run build",
+    "publish": "npm publish --access public",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@astrojs/cloudflare": "catalog:astro-core",
+    "@astrojs/markdoc": "catalog:astro-plugins",
+    "@astrojs/mdx": "catalog:astro-core",
+    "@astrojs/sitemap": "catalog:astro-core",
+    "@astrojs/starlight": "catalog:astro-core",
+    "@knitli/docs-components": "workspace:*",
+    "@nuasite/llm-enhancements": "catalog:astro-plugins",
+    "astro": "catalog:astro-core",
+    "astro-cloudflare-pages-headers": "catalog:astro-plugins",
+    "astro-d2": "catalog:astro-plugins",
+    "astro-favicons": "catalog:astro-core",
+    "rehype-external-links": "^3.0.0",
+    "starlight-announcement": "catalog:starlight-plugins",
+    "starlight-changelogs": "catalog:starlight-plugins",
+    "starlight-heading-badges": "catalog:starlight-plugins",
+    "starlight-links-validator": "catalog:starlight-plugins",
+    "starlight-llms-txt": "catalog:starlight-plugins",
+    "starlight-page-actions": "catalog:starlight-plugins",
+    "starlight-plugin-icons": "catalog:starlight-plugins",
+    "starlight-scroll-to-top": "catalog:starlight-plugins",
+    "starlight-sidebar-topics": "catalog:starlight-plugins",
+    "starlight-tags": "catalog:starlight-plugins",
+    "vite-tsconfig-paths": "catalog:dev-common"
+  },
+  "devDependencies": {
+    "@astrojs/check": "catalog:dev-common",
+    "@astrojs/compiler-rs": "catalog:astro-core",
+    "@biomejs/biome": "catalog:dev-common",
+    "@knitli/tsconfig": "*",
+    "@types/node": "catalog:types",
+    "bun": "catalog:dev-common",
+    "lightningcss": "catalog:optimization",
+    "sharp": "catalog:astro-core",
+    "svgo": "catalog:optimization",
+    "typescript": "catalog:dev-common"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "bun",
+      "version": "catalog:dev-common",
+      "onFail": "download"
+    }
+  }
+}

package/scaffolding/README.md

@@ -0,0 +1,42 @@
+# {{appName}} Docs
+
+Documentation site for {{appName}}, built with [Astro](https://astro.build) + [Starlight](https://starlight.astro.build) using the Knitli docs template.
+
+## Development
+
+```bash
+bun install
+bun run dev
+```
+
+## Deployment
+
+Deployed to Cloudflare Pages:
+
+```bash
+bun run deploy
+```
+
+## Project Structure
+
+```
+.
+├── src/
+│   ├── content/docs/    # Documentation pages (MDX/MD)
+│   ├── styles/          # Site-specific CSS overrides
+│   └── content.config.ts
+├── astro.config.ts      # Uses @knitli/astro-docs-template createConfig
+├── wrangler.jsonc       # Cloudflare Workers configuration
+└── package.json
+```
+
+## Configuration
+
+This site uses `createConfig()` from `@knitli/astro-docs-template` which provides:
+
+- Starlight with Knitli branding (header, footer, theme)
+- Pre-configured plugins (tags, changelogs, LLM text, link validation, etc.)
+- Cloudflare Pages adapter
+- Optimized Vite build settings
+
+Override defaults by passing options to `createConfig()` in `astro.config.ts`.

package/scaffolding/astro.config.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+import createConfig from "@knitli/astro-docs-template/config";
+
+export default createConfig({
+  appName: "{{appName}}",
+  description: "{{description}}",
+  rootDir: import.meta.dirname,
+  llmConfig: {
+    llmDescription: "{{description}}",
+    promotePatterns: ["guides/**", "reference/**"],
+    demotePatterns: ["_*"],
+  },
+});

package/scaffolding/mise.toml

@@ -0,0 +1,65 @@
+# SPDX-FileCopyrightText: 2026 Knitli Inc.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+#:tombi schema.strict = false
+
+[tasks.installdeps]
+description = "Install dependencies for the project"
+run = "bun install"
+tools.bun = "latest"
+
+[tasks.gentypes]
+description = "Generate Cloudflare types for the project"
+run = "bunx wrangler types"
+tools.bun = "latest"
+tools.wrangler = "latest"
+depends = ["installdeps"]
+
+[tasks.dev]
+description = "Start the development server"
+run = "bun run dev"
+tools.bun = "latest"
+depends = ["gentypes"]
+
+[tasks.build]
+description = "Build the project for production"
+run = "bun run build"
+tools.bun = "latest"
+depends = ["gentypes"]
+
+[tasks.deploy]
+description = "Deploy the project to Cloudflare"
+run = '''
+bun run deploy
+'''
+tools.bun = "latest"
+depends = ["build"]
+
+[tasks.clean]
+description = "Clean the project by removing the dist directory"
+run = [
+  "rm -rf dist",
+  "rm -rf .wrangler",
+  "rm -rf node_modules",
+  "rm -rf .astro",
+]
+
+[tasks.clean-install]
+description = "Clean the project and install dependencies"
+depends = ["clean", "installdeps"]
+
+[tasks.fmt]
+description = "Format the codebase using Biome"
+run = "biome format . --write --changed"
+tools.biome = "latest"
+
+[tasks.lint]
+description = "Lint the codebase using Biome"
+run = "biome check . --changed"
+tools.biome = "latest"
+
+[tasks.fix]
+description = "Fix linting issues using Biome"
+run = "biome check . --write --changed"
+tools.biome = "latest"

package/scaffolding/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{name}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "bunx astro build",
+    "deploy": "bunx astro build && bunx wrangler deploy",
+    "dev": "bunx astro dev",
+    "generate-types": "bunx wrangler types",
+    "preview": "bunx astro build && bunx astro preview"
+  },
+  "dependencies": {
+    "@knitli/astro-docs-template": "workspace:*",
+    "@knitli/docs-components": "workspace:*"
+  },
+  "devDependencies": {
+    "@astrojs/check": "catalog:dev-common",
+    "@types/node": "catalog:types",
+    "typescript": "catalog:dev-common",
+    "wrangler": "catalog:dev-common"
+  }
+}

package/scaffolding/public/.assetsignore

@@ -0,0 +1,2 @@
+_worker.js
+_routes.json

package/scaffolding/src/content/docs/guides/getting-started.md

@@ -0,0 +1,18 @@
+---
+title: Getting Started
+description: Set up and start using {{appName}}.
+---
+
+## Installation
+
+```bash
+bun add {{name}}
+```
+
+## Quick Start
+
+Get up and running in minutes.
+
+## Next Steps
+
+- Check the [API Reference](/reference/) for detailed documentation

package/scaffolding/src/content/docs/index.mdx

@@ -0,0 +1,28 @@
+---
+title: "{{appName}} Docs"
+description: "{{description}}"
+template: splash
+hero:
+  tagline: "{{description}}"
+  actions:
+    - text: Get Started
+      link: /{{appNameLower}}/guides/getting-started/
+      icon: right-arrow
+    - text: API Reference
+      link: /{{appNameLower}}/reference/
+      icon: open-book
+      variant: minimal
+---
+
+import { Card, CardGrid } from "@astrojs/starlight/components";
+
+## Next steps
+
+<CardGrid stagger>
+  <Card title="Getting Started" icon="rocket">
+    Follow the [getting started guide](./guides/getting-started/) to set up your environment.
+  </Card>
+  <Card title="Configuration" icon="setting">
+    See the [configuration reference](./reference/) for all available options.
+  </Card>
+</CardGrid>

package/scaffolding/src/content/docs/reference/index.md

@@ -0,0 +1,6 @@
+---
+title: API Reference
+description: "{{appName}} API reference documentation."
+---
+
+Add your API reference documentation here.

package/scaffolding/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

package/scaffolding/src/env.d.ts

@@ -0,0 +1,5 @@
+type Runtime = import("@astrojs/cloudflare").Runtime<Env>;
+
+declare namespace App {
+  interface Locals extends Runtime {}
+}

package/scaffolding/src/styles/custom.css

@@ -0,0 +1,4 @@
+/* Site-specific style overrides.
+ * This file is loaded after the shared Knitli docs theme.
+ * Add custom styles here without modifying shared packages.
+ */

package/scaffolding/tags.yml

@@ -0,0 +1,26 @@
+# sample tags.yml for starlight-tags plugin configuration
+tags:
+  getting-started:
+    label: "Getting Started"
+    description: "Essential first steps"
+    color: "#22c55e"
+    icon: "🚀"
+    priority: 100
+
+  components:
+    label: "Components"
+    description: "UI building blocks"
+    color: "#3b82f6"
+    icon: "🧩"
+
+  advanced:
+    label: "Advanced"
+    description: "For experienced users"
+    color: "#f59e0b"
+    icon: "⚡"
+    difficulty: advanced
+    prerequisites:
+      - getting-started
+
+defaults:
+  color: "#6b7280"

package/scaffolding/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "@knitli/tsconfig/astro-tsconfig.json",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}

package/scaffolding/wrangler.jsonc

@@ -0,0 +1,32 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "account_id": "5def525918a785eeda6decf66cf6b99b",
+  "compatibility_date": "2026-03-17",
+  "compatibility_flags": ["global_fetch_strictly_public", "nodejs_compat"],
+  "name": "{{workerName}}",
+  "main": "@astrojs/cloudflare/entrypoints/server",
+  "assets": {
+    "directory": "./dist",
+    "binding": "ASSETS",
+    "html_handling": "auto-trailing-slash",
+    "not_found_handling": "404-errors",
+    "run_worker_first": false
+  },
+  "observability": {
+    "enabled": true
+  },
+  "placement": {
+    "mode": "smart"
+  },
+  "preview_urls": true,
+  "workers_dev": true,
+  "routes": [
+    {
+      "pattern": "https://docs.knitli.com/{{appNameLower}}/*",
+      "zone_name": "knitli.com"
+    }
+  ],
+  "vars": {
+    "PUBLIC_DOCS_PRODUCT": "{{appName}}"
+  }
+}

package/src/config.ts

@@ -0,0 +1,551 @@
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+// @ts-check
+
+import type { OutgoingHttpHeaders } from "node:http2";
+import cloudflare from "@astrojs/cloudflare";
+import markdoc from "@astrojs/markdoc";
+import mdx from "@astrojs/mdx";
+import sitemap from "@astrojs/sitemap";
+import starlight from "@astrojs/starlight";
+import { DocsAssets } from "@knitli/docs-components";
+import llmEnhancements from "@nuasite/llm-enhancements";
+import { defineConfig, fontProviders } from "astro/config";
+import cloudflarePagesHeaders from "astro-cloudflare-pages-headers";
+import astroD2 from "astro-d2";
+import favicons from "astro-favicons";
+import rehypeExternalLinks from "rehype-external-links";
+import starlightAnnouncement from "starlight-announcement";
+import starlightChangelogs from "starlight-changelogs";
+import starlightHeadingBadges from "starlight-heading-badges";
+import starlightLinksValidator from "starlight-links-validator";
+import starlightLlmsText from "starlight-llms-txt";
+import starlightPageActions from "starlight-page-actions";
+import {
+  starlightIconsIntegration,
+  starlightIconsPlugin,
+} from "starlight-plugin-icons";
+import starlightScrollToTop from "starlight-scroll-to-top";
+import starlightSidebarTopics from "starlight-sidebar-topics";
+import starlightTags from "starlight-tags";
+import { searchForWorkspaceRoot } from "vite";
+import viteTsconfigPaths from "vite-tsconfig-paths";
+
+type defaultIntegration =
+  | "sitemap"
+  | "astroD2"
+  | "markdoc"
+  | "mdx"
+  | "favicons"
+  | "cloudflare-pages-headers";
+
+function nonNullable<T>(value: T): value is NonNullable<T> {
+  return value != null;
+}
+
+// ── Defaults (defined before interface so `typeof` references work) ──
+
+export const {
+  headlineLogoDark,
+  headlineLogoLight,
+  variables,
+  docsStyle,
+  faviconIco,
+  faviconSvg,
+} = DocsAssets;
+
+const shikiCfg = {
+  themes: {
+    light: "catppuccin-latte" as const,
+    dark: "catppuccin-mocha" as const,
+  },
+  bundledLangs: [
+    "ansi",
+    "astro",
+    "bash",
+    "json",
+    "markdown",
+    "python",
+    "rust",
+    "toml",
+    "typescript",
+    "yaml",
+  ],
+  langAlias: {
+    js: "typescript",
+    md: "markdown",
+    py: "python",
+    rs: "rust",
+    sh: "bash",
+    yml: "yaml",
+  },
+};
+
+const imgDomains = [
+  { protocol: "https", hostname: "ui-avatars.com" },
+  { protocol: "https", hostname: "knitli.com" },
+  { protocol: "https", hostname: "*.knitli.com" },
+  { protocol: "https", hostname: "*.githubusercontent.com" },
+  { protocol: "https", hostname: "*.cloudflare.com" },
+];
+
+const defaultFontConfig = [
+  {
+    provider: fontProviders.google(),
+    name: "DM Mono",
+    cssVariable: "--font-sans",
+    weights: [400, 500, 700] as [number, ...number[]],
+    styles: ["normal", "italic"] as [string, ...string[]],
+    subsets: ["latin"] as [string, ...string[]],
+    formats: ["woff2"] as [string, ...string[]],
+    fallbacks: [
+      "Roboto Mono",
+      "Menlo",
+      "Consolas",
+      "DejaVu Sans Mono",
+      "monospace",
+    ],
+  },
+  {
+    provider: fontProviders.google(),
+    name: "JetBrains Mono",
+    cssVariable: "--font-mono",
+    weights: [400, 500, 700] as [number, ...number[]],
+    styles: ["normal", "italic"] as [string, ...string[]],
+    subsets: ["latin"] as [string, ...string[]],
+    formats: ["woff2"] as [string, ...string[]],
+    fallbacks: [
+      "DM Mono",
+      "Roboto Mono",
+      "Menlo",
+      "Consolas",
+      "DejaVu Sans Mono",
+      "monospace",
+    ],
+  },
+];
+
+const codeweaverFontConfig = [
+  { ...defaultFontConfig[1], cssVariable: "--font-sans" },
+  {
+    provider: fontProviders.google(),
+    name: "IBM Plex Mono",
+    cssVariable: "--font-mono",
+    weights: [400, 500, 700] as [number, ...number[]],
+    styles: ["normal", "italic"] as [string, ...string[]],
+    subsets: ["latin"] as [string, ...string[]],
+    formats: ["woff2"] as [string, ...string[]],
+    fallbacks: [
+      "JetBrains Mono",
+      "DM Mono",
+      "Roboto Mono",
+      "Menlo",
+      "Consolas",
+      "DejaVu Sans Mono",
+      "monospace",
+    ],
+  },
+];
+
+// ── Public interface ──
+
+export interface DocsTemplateOptions {
+  appName: string;
+  description: string;
+  llmConfig: {
+    llmDescription: string;
+    promotePatterns: string[];
+    demotePatterns: string[];
+  };
+  rootDir: string;
+  shikiConfig?: typeof shikiCfg;
+  logoDark?: string;
+  logoLight?: string;
+  imageDomains?: typeof imgDomains;
+  is_codeweaver?: boolean;
+  sitemapFilter?: (page: string) => boolean;
+  linkValidationConfig?: Record<string, unknown>;
+  sidebarConfig?: {
+    label: string;
+    autogenerate: { directory: string };
+  }[];
+  unwantedPlugins?: string[];
+  // biome-ignore lint/suspicious/noExplicitAny: plugin configs are opaque pass-throughs
+  pluginConfigs?: Record<string, any>;
+  unwantedIntegrations?: defaultIntegration[];
+  // biome-ignore lint/suspicious/noExplicitAny: integration configs are opaque pass-throughs
+  integrationConfigs?: Record<string, any>;
+  headersConfig?: OutgoingHttpHeaders;
+}
+
+export type IntegrationOptions = Pick<
+  DocsTemplateOptions,
+  "appName" | "sitemapFilter" | "integrationConfigs"
+> & { unwantedIntegrations?: defaultIntegration[] };
+
+const getIntegrations = (options: IntegrationOptions) => {
+  const {
+    appName,
+    sitemapFilter,
+    integrationConfigs,
+    unwantedIntegrations = [],
+  } = options;
+  const defaultIntegrations = [
+    astroD2({ skipGeneration: true }),
+    markdoc(),
+    llmEnhancements({ llmsTxt: false }),
+    mdx(),
+    favicons({
+      name: `${appName} Docs by Knitli`,
+      short_name: `${appName} Docs`,
+      input: {
+        favicons: [faviconSvg],
+      },
+    }),
+    cloudflarePagesHeaders({}),
+    sitemap({
+      filter: sitemapFilter || ((page) => !/\^\/(?!cdn-cgi\/)/.test(page)),
+      changefreq: "weekly",
+      priority: 0.4,
+      lastmod: new Date(),
+      namespaces: {
+        image: false,
+        video: false,
+      },
+    }),
+  ];
+
+  const filtered = defaultIntegrations.filter((integration) => {
+    const name = integration?.name;
+    return !name || !unwantedIntegrations.includes(name as defaultIntegration);
+  });
+
+  if (!integrationConfigs) return filtered;
+
+  const overrides = Object.entries(integrationConfigs)
+    .map(([integrationName, config]) => {
+      switch (integrationName) {
+        case "astroD2":
+          return astroD2(config);
+        case "markdoc":
+          return markdoc(config);
+        case "mdx":
+          return mdx(config);
+        case "favicons":
+          return favicons(config);
+        case "sitemap":
+          return sitemap(config);
+        default:
+          return null;
+      }
+    })
+    .filter(nonNullable);
+
+  return [...filtered, ...overrides];
+};
+
+export type PluginOptions = Pick<
+  DocsTemplateOptions,
+  "appName" | "llmConfig" | "pluginConfigs"
+> & { unwantedPlugins?: string[] };
+
+const get_plugins = (options: PluginOptions) => {
+  const { appName, llmConfig, pluginConfigs, unwantedPlugins = [] } = options;
+  const defaultPlugins = [
+    starlightAnnouncement(),
+    starlightChangelogs(),
+    starlightHeadingBadges(),
+    starlightIconsIntegration(),
+    starlightIconsPlugin(),
+    starlightLinksValidator(),
+    starlightPageActions({
+      baseUrl: `https://docs.knitli.com/${appName.toLowerCase()}`,
+      actions: { claude: true, chatgpt: true, markdown: true },
+      share: true,
+    }),
+    starlightTags({ onInlineTagsNotFound: "warn" }),
+    pluginConfigs?.starlightSidebarTopics
+      ? starlightSidebarTopics(pluginConfigs.starlightSidebarTopics)
+      : null,
+    starlightScrollToTop({ showOnHomepage: false }),
+    // We need to configure starlight-tags with a tags.yml.
+    //starlightTags(),
+    starlightLlmsText({
+      projectName: appName,
+      description: llmConfig.llmDescription,
+      promote: llmConfig.promotePatterns,
+      demote: llmConfig.demotePatterns,
+      minify: {
+        whitespace: true,
+        note: true,
+        details: true,
+      },
+    }),
+  ];
+
+  const filtered = defaultPlugins
+    .filter(nonNullable)
+    .filter((plugin) => !unwantedPlugins.includes(plugin.name));
+
+  if (!pluginConfigs) return filtered;
+
+  const overrides = Object.entries(pluginConfigs)
+    .map(([pluginName, config]) => {
+      switch (pluginName) {
+        case "starlightAnnouncement":
+          return starlightAnnouncement(config);
+        case "starlightIconsIntegration":
+          return starlightIconsIntegration(config);
+        case "starlightIconsPlugin":
+          return starlightIconsPlugin(config);
+        case "starlightLinksValidator":
+          return starlightLinksValidator(config);
+        case "starlightPageActions":
+          return starlightPageActions(config);
+        case "starlightTags":
+          return starlightTags(config);
+        case "starlightScrollToTop":
+          return starlightScrollToTop(config);
+        default:
+          return null;
+      }
+    })
+    .filter(nonNullable);
+
+  return [...filtered, ...overrides];
+};
+
+export default function createConfig(options: DocsTemplateOptions) {
+  const {
+    appName,
+    description,
+    llmConfig,
+    rootDir,
+    shikiConfig = shikiCfg,
+    logoDark = headlineLogoDark,
+    logoLight = headlineLogoLight,
+    imageDomains = imgDomains,
+    is_codeweaver = false,
+    sitemapFilter,
+    sidebarConfig,
+    pluginConfigs,
+    integrationConfigs,
+    unwantedIntegrations,
+    unwantedPlugins,
+    headersConfig,
+  } = options;
+
+  // https://astro.build/config
+  return defineConfig({
+    site: "https://docs.knitli.com",
+    base: `/${appName.toLowerCase()}/`,
+    adapter: cloudflare({
+      prerenderEnvironment: "workerd",
+      experimental: {
+        headersAndRedirectsDevModeSupport: true,
+      },
+      configPath: `${rootDir}/wrangler.jsonc`,
+      imageService: "compile",
+    }),
+    // Image optimization
+    image: {
+      service: {
+        entrypoint: "astro/assets/services/sharp",
+      },
+      responsiveStyles: true,
+      layout: "constrained",
+      remotePatterns: imageDomains,
+    },
+    compressHTML: true,
+    // biome-ignore lint/suspicious/noExplicitAny: Astro's FontFamily generic inference doesn't match spread patterns
+    fonts: (is_codeweaver ? codeweaverFontConfig : defaultFontConfig) as any,
+    // Build optimizations
+    build: {
+      inlineStylesheets: "auto",
+      assets: "_astro",
+    },
+    markdown: {
+      shikiConfig: Object.fromEntries(
+        Object.entries(shikiConfig).filter(([key]) => key !== "bundledLangs"),
+      ),
+      rehypePlugins: [
+        rehypeExternalLinks({
+          content: { type: "text", value: " 🔗" },
+          rel: ["nofollow"],
+        }),
+      ],
+    },
+    server: {
+      headers: headersConfig,
+    },
+    trailingSlash: "always",
+    // Vite configuration for better bundling
+    vite: {
+      server: {
+        fs: {
+          allow: [searchForWorkspaceRoot(rootDir)],
+        },
+      },
+      assetsInclude: [
+        "src/*.webp",
+        "src/*.png",
+        "src/*.jpg",
+        "src/*.jpeg",
+        "src/*.svg",
+        "src/*.avif",
+      ],
+      plugins: [viteTsconfigPaths({ loose: true })],
+      define: {
+        "import.meta.env.PUBLIC_DOCS_PRODUCT": JSON.stringify(appName),
+      },
+      build: {
+        cssMinify: "lightningcss",
+        minify: "esbuild",
+        cssCodeSplit: true,
+        rollupOptions: {
+          external: ["shiki", "shiki-esbuild"],
+          output: {
+            format: "es",
+            dir: `${rootDir}/dist/_astro/`,
+            compact: true,
+            interop: "esModule",
+            experimentalMinChunkSize: 10000,
+            banner: `
+          /* SPDX-FileCopyrightText: 2026 Knitli Inc.
+          * SPDX-License-Identifier: MIT OR Apache-2.0
+          */
+          `.trim(),
+            minifyInternalExports: true,
+            sourcemap: false,
+            generatedCode: {
+              arrowFunctions: true,
+              constBindings: true,
+              objectShorthand: true,
+              symbols: true,
+            },
+            entryFileNames: "assets/[name]-[hash].js",
+            chunkFileNames: "assets/[name]-[hash].js",
+            assetFileNames: "assets/[name]-[hash][extname]",
+          },
+          treeshake: "smallest",
+        },
+        ssr: false,
+      },
+      css: {
+        lightningcss: {},
+      },
+    },
+    prefetch: {
+      defaultStrategy: "viewport",
+    },
+    prerenderConflictBehavior: "warn",
+    experimental: {
+      chromeDevtoolsWorkspace: true,
+      clientPrerender: true,
+      contentIntellisense: true,
+      queuedRendering: {
+        contentCache: true,
+        enabled: true,
+      },
+      rustCompiler: true,
+      svgo: {
+        plugins: [
+          {
+            name: "preset-default",
+            params: {
+              overrides: {
+                removeMetadata: false,
+              },
+            },
+          },
+        ],
+      },
+    },
+
+    // Static site generation for Cloudflare
+    output: "static",
+    integrations: [
+      ...getIntegrations({
+        appName,
+        sitemapFilter,
+        integrationConfigs,
+        unwantedIntegrations,
+      }),
+      starlight({
+        title: `${appName} Docs`,
+        pagefind: true,
+        description: description,
+        logo: {
+          dark: logoDark,
+          light: logoLight,
+          alt: is_codeweaver ? "CodeWeaver Logo" : "Knitli Logo",
+          replacesTitle: true,
+        },
+        editLink: {
+          baseUrl: `https://github.com/knitli/${appName.toLowerCase()}/edit/main/docs-site/src`,
+        },
+        expressiveCode: {
+          useStarlightDarkModeSwitch: true,
+          themes: [shikiConfig.themes.dark, shikiConfig.themes.light],
+          removeUnusedThemes: true,
+          shiki: {
+            ...Object.fromEntries(
+              Object.entries(shikiConfig).filter(([key]) => key !== "themes"),
+            ),
+          },
+        },
+        plugins: get_plugins({
+          appName,
+          llmConfig,
+          pluginConfigs,
+          unwantedPlugins,
+          // biome-ignore lint/suspicious/noExplicitAny: Starlight plugin types are complex Zod inferences
+        }) as any[],
+        social: [
+          {
+            icon: "github",
+            label: "GitHub",
+            href: `https://github.com/knitli/${appName.toLowerCase()}`,
+          },
+        ],
+        components: {
+          Footer: "@knitli/docs-components/Footer.astro",
+          PageFrame: "@knitli/docs-components/PageFrame.astro",
+        },
+        customCss: [variables, docsStyle, `${rootDir}/src/styles/custom.css`],
+        head: [
+          {
+            tag: "meta",
+            attrs: {
+              property: "og:image",
+              content: `https://docs.knitli.com/${appName.toLowerCase()}/og-image.png`,
+            },
+          },
+          {
+            tag: "meta",
+            attrs: {
+              property: "twitter:card",
+              content: "summary_large_image",
+            },
+          },
+        ],
+        sidebar: sidebarConfig || [
+          {
+            label: "Guides",
+            autogenerate: { directory: "guides" },
+          },
+          {
+            label: "Examples",
+            autogenerate: { directory: "examples" },
+          },
+          {
+            label: "Reference",
+            autogenerate: { directory: "reference" },
+          },
+        ],
+      }),
+    ],
+  });
+}

package/src/index.ts

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export { type DocsTemplateOptions, default as createConfig } from "./config.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCAFFOLDING_DIR = resolve(__dirname, "../scaffolding");
+
+export interface InitOptions {
+  /** Display name for the product (e.g. "Recoco", "CodeWeaver") */
+  appName: string;
+  /** npm package name (e.g. "@knitli-site/recoco-docs") */
+  name: string;
+  /** Short product description */
+  description: string;
+  /** Cloudflare Worker name (e.g. "recoco-docs") */
+  workerName?: string;
+  /** Whether this is a CodeWeaver-branded site */
+  is_codeweaver?: boolean;
+}
+
+/** File extensions that should have placeholder substitution applied */
+const TEXT_EXTENSIONS = new Set([
+  ".ts",
+  ".js",
+  ".mjs",
+  ".json",
+  ".jsonc",
+  ".md",
+  ".mdx",
+  ".yml",
+  ".yaml",
+  ".css",
+  ".html",
+  ".astro",
+  ".d.ts",
+]);
+
+function isTextFile(filePath: string): boolean {
+  return TEXT_EXTENSIONS.has(filePath.slice(filePath.lastIndexOf(".")));
+}
+
+function buildReplacements(options: InitOptions): Record<string, string> {
+  return {
+    "{{appName}}": options.appName,
+    "{{appNameLower}}": options.appName.toLowerCase(),
+    "{{name}}": options.name,
+    "{{description}}": options.description,
+    "{{workerName}}":
+      options.workerName ?? `${options.appName.toLowerCase()}-docs`,
+  };
+}
+
+function applyReplacements(
+  content: string,
+  replacements: Record<string, string>,
+): string {
+  let result = content;
+  for (const [placeholder, value] of Object.entries(replacements)) {
+    result = result.replaceAll(placeholder, value);
+  }
+  return result;
+}
+
+/**
+ * Initialize a new Knitli docs site from the template scaffolding.
+ *
+ * Copies all files from the scaffolding directory to the target path,
+ * applying placeholder substitution to text files.
+ *
+ * @param targetPath - Directory to scaffold into (will be created if it doesn't exist)
+ * @param options - Configuration for placeholder substitution
+ * @returns List of files created
+ */
+export function initDocsTemplate(
+  targetPath: string,
+  options: InitOptions,
+): string[] {
+  const target = resolve(targetPath);
+  const replacements = buildReplacements(options);
+  const created: string[] = [];
+
+  if (!existsSync(SCAFFOLDING_DIR)) {
+    throw new Error(`Scaffolding directory not found at ${SCAFFOLDING_DIR}`);
+  }
+
+  function copyDir(srcDir: string, destDir: string) {
+    if (!existsSync(destDir)) {
+      mkdirSync(destDir, { recursive: true });
+    }
+
+    for (const entry of readdirSync(srcDir)) {
+      const srcPath = join(srcDir, entry);
+      const destPath = join(destDir, entry);
+      const stat = statSync(srcPath);
+
+      if (stat.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else if (isTextFile(srcPath)) {
+        const content = readFileSync(srcPath, "utf-8");
+        const processed = applyReplacements(content, replacements);
+        mkdirSync(dirname(destPath), { recursive: true });
+        writeFileSync(destPath, processed, "utf-8");
+        created.push(destPath);
+      } else {
+        mkdirSync(dirname(destPath), { recursive: true });
+        cpSync(srcPath, destPath);
+        created.push(destPath);
+      }
+    }
+  }
+
+  copyDir(SCAFFOLDING_DIR, target);
+  return created;
+}