@knitli/astro-docs-template 0.1.2 → 0.2.0

package/{dist/config.js → src/config.ts}

@@ -1,43 +1,65 @@
-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 { fontProviders, defineConfig } 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';
+// SPDX-FileCopyrightText: 2026 Knitli Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
 
-function nonNullable(value) {
+// @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;
 }
-const {
+
+// ── Defaults (defined before interface so `typeof` references work) ──
+
+export const {
   headlineLogoDark,
   headlineLogoLight,
   variables,
   docsStyle,
   faviconIco,
-  faviconSvg
+  faviconSvg,
 } = DocsAssets;
+
 const shikiCfg = {
   themes: {
-    light: "catppuccin-latte",
-    dark: "catppuccin-mocha"
+    light: "catppuccin-latte" as const,
+    dark: "catppuccin-mocha" as const,
   },
   bundledLangs: [
     "ansi",
@@ -49,7 +71,7 @@ const shikiCfg = {
     "rust",
     "toml",
     "typescript",
-    "yaml"
+    "yaml",
   ],
   langAlias: {
     js: "typescript",
@@ -57,61 +79,64 @@ const shikiCfg = {
     py: "python",
     rs: "rust",
     sh: "bash",
-    yml: "yaml"
-  }
+    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" }
+  { protocol: "https", hostname: "*.cloudflare.com" },
 ];
+
 const defaultFontConfig = [
   {
     provider: fontProviders.google(),
     name: "DM Mono",
     cssVariable: "--font-sans",
-    weights: [400, 500, 700],
-    styles: ["normal", "italic"],
-    subsets: ["latin"],
-    formats: ["woff2"],
+    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"
-    ]
+      "monospace",
+    ],
   },
   {
     provider: fontProviders.google(),
     name: "JetBrains Mono",
     cssVariable: "--font-mono",
-    weights: [400, 500, 700],
-    styles: ["normal", "italic"],
-    subsets: ["latin"],
-    formats: ["woff2"],
+    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"
-    ]
-  }
+      "monospace",
+    ],
+  },
 ];
+
 const codeweaverFontConfig = [
   { ...defaultFontConfig[1], cssVariable: "--font-sans" },
   {
     provider: fontProviders.google(),
     name: "IBM Plex Mono",
     cssVariable: "--font-mono",
-    weights: [400, 500, 700],
-    styles: ["normal", "italic"],
-    subsets: ["latin"],
-    formats: ["woff2"],
+    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",
@@ -119,16 +144,53 @@ const codeweaverFontConfig = [
       "Menlo",
       "Consolas",
       "DejaVu Sans Mono",
-      "monospace"
-    ]
-  }
+      "monospace",
+    ],
+  },
 ];
-const getIntegrations = (options) => {
+
+// ── 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 = []
+    unwantedIntegrations = [],
   } = options;
   const defaultIntegrations = [
     astroD2({ skipGeneration: true }),
@@ -139,45 +201,57 @@ const getIntegrations = (options) => {
       name: `${appName} Docs by Knitli`,
       short_name: `${appName} Docs`,
       input: {
-        favicons: [faviconSvg]
-      }
+        favicons: [faviconSvg],
+      },
     }),
     cloudflarePagesHeaders({}),
     sitemap({
       filter: sitemapFilter || ((page) => !/\^\/(?!cdn-cgi\/)/.test(page)),
       changefreq: "weekly",
       priority: 0.4,
-      lastmod: /* @__PURE__ */ new Date(),
+      lastmod: new Date(),
       namespaces: {
         image: false,
-        video: false
-      }
-    })
+        video: false,
+      },
+    }),
   ];
+
   const filtered = defaultIntegrations.filter((integration) => {
     const name = integration?.name;
-    return !name || !unwantedIntegrations.includes(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);
+
+  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];
 };
-const get_plugins = (options) => {
+
+export type PluginOptions = Pick<
+  DocsTemplateOptions,
+  "appName" | "llmConfig" | "pluginConfigs"
+> & { unwantedPlugins?: string[] };
+
+const get_plugins = (options: PluginOptions) => {
   const { appName, llmConfig, pluginConfigs, unwantedPlugins = [] } = options;
   const defaultPlugins = [
     starlightAnnouncement(),
@@ -189,10 +263,12 @@ const get_plugins = (options) => {
     starlightPageActions({
       baseUrl: `https://docs.knitli.com/${appName.toLowerCase()}`,
       actions: { claude: true, chatgpt: true, markdown: true },
-      share: true
+      share: true,
     }),
     starlightTags({ onInlineTagsNotFound: "warn" }),
-    pluginConfigs?.starlightSidebarTopics ? starlightSidebarTopics(pluginConfigs.starlightSidebarTopics) : null,
+    pluginConfigs?.starlightSidebarTopics
+      ? starlightSidebarTopics(pluginConfigs.starlightSidebarTopics)
+      : null,
     starlightScrollToTop({ showOnHomepage: false }),
     // We need to configure starlight-tags with a tags.yml.
     //starlightTags(),
@@ -204,35 +280,44 @@ const get_plugins = (options) => {
       minify: {
         whitespace: true,
         note: true,
-        details: true
-      }
-    })
+        details: true,
+      },
+    }),
   ];
-  const filtered = defaultPlugins.filter(nonNullable).filter((plugin) => !unwantedPlugins.includes(plugin.name));
+
+  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);
+
+  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];
 };
-function createConfig(options) {
+
+export default function createConfig(options: DocsTemplateOptions) {
   const {
     appName,
     description,
@@ -249,57 +334,59 @@ function createConfig(options) {
     integrationConfigs,
     unwantedIntegrations,
     unwantedPlugins,
-    headersConfig
+    headersConfig,
   } = options;
+
+  // https://astro.build/config
   return defineConfig({
     site: "https://docs.knitli.com",
     base: `/${appName.toLowerCase()}/`,
     adapter: cloudflare({
       prerenderEnvironment: "workerd",
       experimental: {
-        headersAndRedirectsDevModeSupport: true
+        headersAndRedirectsDevModeSupport: true,
       },
       configPath: `${rootDir}/wrangler.jsonc`,
-      imageService: "compile"
+      imageService: "compile",
     }),
     // Image optimization
     image: {
       service: {
-        entrypoint: "astro/assets/services/sharp"
+        entrypoint: "astro/assets/services/sharp",
       },
       responsiveStyles: true,
       layout: "constrained",
-      remotePatterns: imageDomains
+      remotePatterns: imageDomains,
     },
     compressHTML: true,
     // biome-ignore lint/suspicious/noExplicitAny: Astro's FontFamily generic inference doesn't match spread patterns
-    fonts: is_codeweaver ? codeweaverFontConfig : defaultFontConfig,
+    fonts: (is_codeweaver ? codeweaverFontConfig : defaultFontConfig) as any,
     // Build optimizations
     build: {
       inlineStylesheets: "auto",
-      assets: "_astro"
+      assets: "_astro",
     },
     markdown: {
       shikiConfig: Object.fromEntries(
-        Object.entries(shikiConfig).filter(([key]) => key !== "bundledLangs")
+        Object.entries(shikiConfig).filter(([key]) => key !== "bundledLangs"),
       ),
       rehypePlugins: [
         rehypeExternalLinks({
           content: { type: "text", value: " ↗" },
-          rel: ["nofollow"]
-        })
-      ]
+          rel: ["nofollow"],
+        }),
+      ],
     },
     server: {
-      headers: headersConfig
+      headers: headersConfig,
     },
     trailingSlash: "always",
     // Vite configuration for better bundling
     vite: {
       server: {
         fs: {
-          allow: [searchForWorkspaceRoot(rootDir)]
-        }
+          allow: [searchForWorkspaceRoot(rootDir)],
+        },
       },
       assetsInclude: [
         "src/*.webp",
@@ -307,11 +394,11 @@ function createConfig(options) {
         "src/*.jpg",
         "src/*.jpeg",
         "src/*.svg",
-        "src/*.avif"
+        "src/*.avif",
       ],
       plugins: [viteTsconfigPaths({ loose: true })],
       define: {
-        "import.meta.env.PUBLIC_DOCS_PRODUCT": JSON.stringify(appName)
+        "import.meta.env.PUBLIC_DOCS_PRODUCT": JSON.stringify(appName),
       },
       build: {
         cssMinify: "lightningcss",
@@ -324,7 +411,7 @@ function createConfig(options) {
             dir: `${rootDir}/dist/_astro/`,
             compact: true,
             interop: "esModule",
-            experimentalMinChunkSize: 1e4,
+            experimentalMinChunkSize: 10000,
             banner: `
           /* SPDX-FileCopyrightText: 2026 Knitli Inc.
           * SPDX-License-Identifier: MIT OR Apache-2.0
@@ -336,22 +423,22 @@ function createConfig(options) {
               arrowFunctions: true,
               constBindings: true,
               objectShorthand: true,
-              symbols: true
+              symbols: true,
             },
             entryFileNames: "assets/[name]-[hash].js",
             chunkFileNames: "assets/[name]-[hash].js",
-            assetFileNames: "assets/[name]-[hash][extname]"
+            assetFileNames: "assets/[name]-[hash][extname]",
           },
-          treeshake: "smallest"
+          treeshake: "smallest",
         },
-        ssr: false
+        ssr: false,
       },
       css: {
-        lightningcss: {}
-      }
+        lightningcss: {},
+      },
     },
     prefetch: {
-      defaultStrategy: "viewport"
+      defaultStrategy: "viewport",
     },
     prerenderConflictBehavior: "warn",
     experimental: {
@@ -360,7 +447,7 @@ function createConfig(options) {
       contentIntellisense: true,
       queuedRendering: {
         contentCache: true,
-        enabled: true
+        enabled: true,
       },
       rustCompiler: true,
       svgo: {
@@ -369,13 +456,14 @@ function createConfig(options) {
             name: "preset-default",
             params: {
               overrides: {
-                removeMetadata: false
-              }
-            }
-          }
-        ]
-      }
+                removeMetadata: false,
+              },
+            },
+          },
+        ],
+      },
     },
+
     // Static site generation for Cloudflare
     output: "static",
     integrations: [
@@ -383,20 +471,20 @@ function createConfig(options) {
         appName,
         sitemapFilter,
         integrationConfigs,
-        unwantedIntegrations
+        unwantedIntegrations,
       }),
       starlight({
         title: `${appName} Docs`,
         pagefind: true,
-        description,
+        description: description,
         logo: {
           dark: logoDark,
           light: logoLight,
           alt: is_codeweaver ? "CodeWeaver Logo" : "Knitli Logo",
-          replacesTitle: true
+          replacesTitle: true,
         },
         editLink: {
-          baseUrl: `https://github.com/knitli/${appName.toLowerCase()}/edit/main/docs-site/src`
+          baseUrl: `https://github.com/knitli/${appName.toLowerCase()}/edit/main/docs-site/src`,
         },
         expressiveCode: {
           useStarlightDarkModeSwitch: true,
@@ -404,27 +492,27 @@ function createConfig(options) {
           removeUnusedThemes: true,
           shiki: {
             ...Object.fromEntries(
-              Object.entries(shikiConfig).filter(([key]) => key !== "themes")
-            )
-          }
+              Object.entries(shikiConfig).filter(([key]) => key !== "themes"),
+            ),
+          },
         },
         plugins: get_plugins({
           appName,
           llmConfig,
           pluginConfigs,
-          unwantedPlugins
+          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()}`
-          }
+            href: `https://github.com/knitli/${appName.toLowerCase()}`,
+          },
         ],
         components: {
           Footer: "@knitli/docs-components/Footer.astro",
-          PageFrame: "@knitli/docs-components/PageFrame.astro"
+          PageFrame: "@knitli/docs-components/PageFrame.astro",
         },
         customCss: [variables, docsStyle, `${rootDir}/src/styles/custom.css`],
         head: [
@@ -432,34 +520,32 @@ function createConfig(options) {
             tag: "meta",
             attrs: {
               property: "og:image",
-              content: `https://docs.knitli.com/${appName.toLowerCase()}/og-image.png`
-            }
+              content: `https://docs.knitli.com/${appName.toLowerCase()}/og-image.png`,
+            },
           },
           {
             tag: "meta",
             attrs: {
               property: "twitter:card",
-              content: "summary_large_image"
-            }
-          }
+              content: "summary_large_image",
+            },
+          },
         ],
         sidebar: sidebarConfig || [
           {
             label: "Guides",
-            autogenerate: { directory: "guides" }
+            autogenerate: { directory: "guides" },
           },
           {
             label: "Examples",
-            autogenerate: { directory: "examples" }
+            autogenerate: { directory: "examples" },
           },
           {
             label: "Reference",
-            autogenerate: { directory: "reference" }
-          }
-        ]
-      })
-    ]
+            autogenerate: { directory: "reference" },
+          },
+        ],
+      }),
+    ],
   });
 }
-
-export { createConfig as default, docsStyle, faviconIco, faviconSvg, headlineLogoDark, headlineLogoLight, variables };