@abstractdata/create-docs 0.2.3

package/template/scripts/build-ts-docs.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+/**
+ * build-ts-docs.mjs
+ *
+ * Generates Starlight-compatible Markdown API reference from a
+ * TypeScript project's source via TypeDoc + typedoc-plugin-markdown.
+ *
+ * Reads `scripts/ts-autodoc.json` for configuration:
+ *   - entryPoints:       array of TS entry files (e.g. ["../../my-lib/src/index.ts"])
+ *   - tsconfig:          path to the project's tsconfig.json
+ *   - outputDir:         where the generated .md pages land
+ *   - githubPages:       pass through to TypeDoc
+ *   - skipErrorChecking: pass through to TypeDoc
+ *   - repoUrl:           (optional) base URL for "View on GitHub" footer
+ *   - repoBranch:        (optional) default 'main'
+ *   - versions:          (optional) array of { tag, label, default } for versioned docs.
+ *                        When present, each tag triggers an independent build
+ *                        from a `git worktree` checkout into <outputDir>/<safeTag>/.
+ *                        The default version is also aliased at the un-versioned
+ *                        URL so existing links keep resolving.
+ *
+ * For each module, TypeDoc emits a markdown file. The orchestrator
+ * post-processes each one to add Starlight `title:` frontmatter, a `version:`
+ * field when versioned, and a stale-version banner on non-default builds.
+ *
+ * Run:
+ *   bun run docs:ts
+ *
+ * Requires:
+ *   bun add -d typedoc typedoc-plugin-markdown
+ */
+import { execSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+const CONFIG_PATH = resolve(__dirname, 'ts-autodoc.json');
+
+const c = {
+  reset: '\x1b[0m', dim: '\x1b[2m', cyan: '\x1b[36m', gold: '\x1b[33m',
+  red: '\x1b[31m', green: '\x1b[32m',
+};
+const log = (...a) => console.log(...a);
+const die = (msg) => { console.error(`${c.red}error${c.reset} ${msg}`); process.exit(1); };
+
+// ─── Load config ──────────────────────────────────────────────────────
+if (!existsSync(CONFIG_PATH)) die(`Missing config: ${CONFIG_PATH}`);
+const cfg = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+if (!Array.isArray(cfg.entryPoints) || cfg.entryPoints.length === 0) {
+  die('ts-autodoc.json: `entryPoints` must be a non-empty array.');
+}
+
+const ROOT_OUTPUT = resolve(PROJECT_ROOT, cfg.outputDir ?? 'src/content/docs/api/ts');
+const ROOT_TSCONFIG = cfg.tsconfig ? resolve(PROJECT_ROOT, cfg.tsconfig) : null;
+
+// ─── Verify TypeDoc available ─────────────────────────────────────────
+log(`${c.dim}→ checking typedoc${c.reset}`);
+try {
+  execSync('npx --no-install typedoc --version', { cwd: PROJECT_ROOT, stdio: 'ignore' });
+} catch {
+  die(`typedoc not found. Install it as a dev dep:
+    bun add -d typedoc typedoc-plugin-markdown
+  Then re-run this script.`);
+}
+
+// ─── Versioning setup ────────────────────────────────────────────────
+function findGitRoot(start) {
+  let dir = start;
+  while (true) {
+    if (existsSync(join(dir, '.git'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+const versions = Array.isArray(cfg.versions) ? cfg.versions : null;
+let SOURCE_REPO_ROOT = null;
+let ENTRY_POINTS_REL = null;
+let TSCONFIG_REL = null;
+if (versions) {
+  if (versions.length === 0) die('`versions` is an empty array — set it to null/omit, or list at least one version.');
+  if (!versions.some((v) => v.tag)) die('`versions[].tag` is required on every entry.');
+  if (versions.filter((v) => v.default).length > 1) die('Only one `versions[].default: true` allowed.');
+  if (!versions.some((v) => v.default)) {
+    log(`${c.gold}warn${c.reset} no version marked default; treating the first one (${versions[0].tag}) as default`);
+    versions[0].default = true;
+  }
+  // Use the first entry point to find the source git repo. All entries
+  // must live under the same repo for versioned builds to make sense.
+  const firstEntry = resolve(PROJECT_ROOT, cfg.entryPoints[0]);
+  SOURCE_REPO_ROOT = findGitRoot(firstEntry);
+  if (!SOURCE_REPO_ROOT) {
+    die(`versions[] is configured but no .git directory was found above ${firstEntry}.\n  Versioned builds require the source to be a git checkout.`);
+  }
+  ENTRY_POINTS_REL = cfg.entryPoints.map((e) =>
+    relative(SOURCE_REPO_ROOT, resolve(PROJECT_ROOT, e)),
+  );
+  TSCONFIG_REL = ROOT_TSCONFIG ? relative(SOURCE_REPO_ROOT, ROOT_TSCONFIG) : null;
+  log(`${c.dim}→ source repo: ${SOURCE_REPO_ROOT}${c.reset}`);
+  log(`${c.dim}→ entryPoints (rel): ${ENTRY_POINTS_REL.join(', ')}${c.reset}`);
+}
+
+// Make a tag filesystem-safe for use as a directory name. We have to be
+// strict here: Astro's slug normalizer strips dots from URL segments
+// (`0.1.0` → `010`), so if our directory names contain dots the URL the
+// VersionPicker constructs won't match the rendered URL. Convert dots
+// to dashes (and any other non-alphanumeric to dashes).
+//   v0.3.0 → 0-3-0
+//   v1.0.0-rc.1 → 1-0-0-rc-1
+function safeTag(tag) {
+  return tag.replace(/^v/, '').replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+
+// ─── Per-build pipeline ──────────────────────────────────────────────
+function buildOnce({ entryPoints, tsconfig, version }) {
+  const outDir = version ? join(ROOT_OUTPUT, safeTag(version.tag)) : ROOT_OUTPUT;
+  mkdirSync(outDir, { recursive: true });
+
+  const tagPrefix = version ? `${c.cyan}[${version.label ?? version.tag}]${c.reset} ` : '';
+  log(`${c.dim}→ ${tagPrefix}generating TypeScript API pages${c.reset}`);
+
+  const args = [
+    '--plugin', 'typedoc-plugin-markdown',
+    '--out', outDir,
+    '--readme', 'none',
+    '--hideBreadcrumbs', 'true',
+    '--hidePageHeader', 'true',
+  ];
+  if (tsconfig) args.push('--tsconfig', tsconfig);
+  if (cfg.skipErrorChecking) args.push('--skipErrorChecking');
+  for (const entry of entryPoints) args.push(entry);
+
+  try {
+    execSync(`npx typedoc ${args.map((a) => `"${a}"`).join(' ')}`,
+      { cwd: PROJECT_ROOT, stdio: 'inherit' });
+  } catch {
+    log(`${c.red}error${c.reset} ${tagPrefix}typedoc failed; skipping this build`);
+    return;
+  }
+
+  // Post-process every emitted .md
+  log(`${c.dim}→ ${tagPrefix}adding Starlight frontmatter${c.reset}`);
+
+  function walk(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) out.push(...walk(full));
+      else if (entry.name.endsWith('.md')) out.push(full);
+    }
+    return out;
+  }
+
+  const pages = [];
+  for (const file of walk(outDir)) {
+    let content = readFileSync(file, 'utf8');
+    if (content.startsWith('---\n')) continue;
+
+    const h1 = content.match(/^# (.+?)$/m);
+    const fallbackTitle = relative(outDir, file).replace(/\.md$/, '').replace(/[\\/_]/g, ' ');
+    const title = (h1?.[1] ?? fallbackTitle).trim().replace(/\\_/g, '_');
+    const body = h1 ? content.replace(h1[0] + '\n', '') : content;
+
+    const desc = body.split('\n').find((l) => {
+      const t = l.trim();
+      if (!t) return false;
+      if (/^#{1,6} /.test(t)) return false;
+      if (t.startsWith('```')) return false;
+      if (t.startsWith('|')) return false;
+      if (/^[-*+] /.test(t)) return false;
+      if (/^<[^>]+>/.test(t)) return false;
+      return true;
+    });
+    const description = (desc ?? `API reference for \`${title}\`.`)
+      .trim().replace(/`/g, '').replace(/"/g, "'").slice(0, 160);
+
+    const fmLines = ['---', `title: ${title}`, `description: "${description}"`];
+    if (version) {
+      // Emit version metadata. `versionDefault: true` lets the bundled
+      // <VersionPicker> auto-discover which version to pre-select without
+      // duplicating the canonical list outside the autodoc JSON config.
+      fmLines.push(`version: "${version.tag}"`);
+      if (version.label) fmLines.push(`versionLabel: "${version.label}"`);
+      if (version.default) fmLines.push(`versionDefault: true`);
+    }
+    fmLines.push('---', '');
+    const frontmatter = fmLines.join('\n');
+    pages.push({ file, title, description, body, frontmatter });
+  }
+
+  // Thin-page post-processor (TS)
+  let bannered = 0, enriched = 0;
+  const landingPage = pages.find((p) => /^(index|readme|globals|modules)\.md$/i.test(relative(outDir, p.file)));
+
+  for (const page of pages) {
+    const proseLines = page.body.split('\n').filter((l) => {
+      const t = l.trim();
+      if (!t) return false;
+      if (/^#{1,6} /.test(t)) return false;
+      if (t.startsWith('```')) return false;
+      if (t.startsWith('|') || /^[-=]{3,}/.test(t)) return false;
+      if (/^[-*+] /.test(t)) return false;
+      if (/^<[^>]+>/.test(t)) return false;
+      return true;
+    }).length;
+    const bodyChars = page.body.replace(/\s+/g, '').length;
+    const isThin = bodyChars < 150 && proseLines < 1;
+
+    let newBody = page.body;
+    let touched = false;
+
+    if (version && !version.default) {
+      const defaultV = (cfg.versions ?? []).find((v) => v.default);
+      const latestLabel = defaultV ? (defaultV.label ?? defaultV.tag) : 'latest';
+      const apiBase = `/${cfg.outputDir.replace(/^src\/content\/docs\/?/, '').replace(/\/$/, '')}`;
+      const sameRel = relative(outDir, page.file).replace(/\.md$/, '');
+      const latestPath = defaultV
+        ? `${apiBase}/${safeTag(defaultV.tag)}/${sameRel}/`
+        : null;
+      const link = latestPath ? `[${latestLabel} →](${latestPath})` : latestLabel;
+      const stale = [
+        '', `:::caution[Older version]`,
+        `You're viewing **${version.label ?? version.tag}**. Latest is ${link}.`,
+        ':::', '',
+      ].join('\n');
+      newBody = stale + newBody;
+      touched = true;
+    }
+
+    if (page === landingPage) {
+      const others = pages.filter((p) => p !== landingPage);
+      if (others.length > 0) {
+        const lines = ['', '## Submodules', ''];
+        for (const sib of others) {
+          const rel = relative(outDir, sib.file).replace(/\.md$/, '');
+          const summary = sib.description && !sib.description.startsWith('API reference for')
+            ? ` — ${sib.description}` : '';
+          lines.push(`- [\`${sib.title}\`](./${rel}.md)${summary}`);
+        }
+        lines.push('');
+        const submodulesSection = lines.join('\n');
+        if (isThin) {
+          newBody = newBody + `\nTop-level entry — see modules below for the full API surface.\n${submodulesSection}`;
+        } else {
+          newBody = newBody.replace(/\s+$/, '') + '\n' + submodulesSection;
+        }
+        enriched += 1;
+        touched = true;
+        log(`${c.green}  ✓${c.reset} ${tagPrefix}added Submodules to ${relative(outDir, page.file)}`);
+      }
+    } else if (isThin) {
+      const noteBlock = [
+        '', ':::note[This page is sparse]',
+        `The auto-generated reference for \`${page.title}\` is short. Expanding the leading \`/** ... */\` TSDoc comment in the source (purpose, when to use it, a tiny example) would populate this page with real context.`,
+        ':::', '',
+      ].join('\n');
+      newBody = noteBlock + newBody;
+      bannered += 1;
+      touched = true;
+      log(`${c.gold}  ⚠${c.reset} ${tagPrefix}thin-page banner on ${relative(outDir, page.file)}`);
+    }
+
+    if (touched && cfg.repoUrl) {
+      const branch = version ? version.tag : (cfg.repoBranch ?? 'main');
+      const repo = cfg.repoUrl.replace(/\/$/, '');
+      newBody = newBody.replace(/\s+$/, '') +
+        `\n\n## See also\n\n- [View on GitHub](${repo}/tree/${branch})\n`;
+    }
+
+    writeFileSync(page.file, page.frontmatter + newBody);
+  }
+
+  log('');
+  log(`${c.green}✓${c.reset} ${tagPrefix}Generated ${c.gold}${pages.length}${c.reset} TS API page${pages.length === 1 ? '' : 's'} in ${c.cyan}${relative(PROJECT_ROOT, outDir)}${c.reset}/`);
+  if (enriched || bannered) log(`${c.dim}  ${enriched} landing page${enriched === 1 ? '' : 's'} enriched, ${bannered} thin page${bannered === 1 ? '' : 's'} flagged${c.reset}`);
+}
+
+// ─── Run: single-build or per-version with worktrees ──────────────────
+const createdWorktrees = [];
+
+function cleanup() {
+  for (const wt of createdWorktrees) {
+    try {
+      execSync(`git -C "${SOURCE_REPO_ROOT}" worktree remove --force "${wt}"`, { stdio: 'ignore' });
+    } catch {
+      try { rmSync(wt, { recursive: true, force: true }); } catch {}
+    }
+  }
+}
+process.on('exit', cleanup);
+process.on('SIGINT', () => { cleanup(); process.exit(130); });
+
+try {
+  if (!versions) {
+    buildOnce({
+      entryPoints: cfg.entryPoints.map((e) => resolve(PROJECT_ROOT, e)),
+      tsconfig: ROOT_TSCONFIG,
+      version: null,
+    });
+  } else {
+    for (const v of versions) {
+      const wt = mkdtempSync(join(tmpdir(), `tsdoc-${safeTag(v.tag)}-`));
+      createdWorktrees.push(wt);
+      log(`${c.dim}→ git worktree add ${wt} ${v.tag}${c.reset}`);
+      try {
+        execSync(`git -C "${SOURCE_REPO_ROOT}" worktree add --detach "${wt}" "${v.tag}"`, { stdio: 'inherit' });
+      } catch {
+        log(`${c.red}error${c.reset} failed to create worktree for ${v.tag}; skipping`);
+        continue;
+      }
+      const wtEntries = ENTRY_POINTS_REL.map((rel) => join(wt, rel));
+      const wtTsconfig = TSCONFIG_REL ? join(wt, TSCONFIG_REL) : null;
+      const missing = wtEntries.find((p) => !existsSync(p));
+      if (missing) {
+        log(`${c.gold}warn${c.reset} ${v.tag}: entry point ${missing} not found; skipping`);
+        continue;
+      }
+      buildOnce({ entryPoints: wtEntries, tsconfig: wtTsconfig, version: v });
+    }
+
+    // Alias the default version at un-versioned URLs
+    const defaultV = versions.find((v) => v.default);
+    if (defaultV) {
+      log(`${c.dim}→ aliasing ${defaultV.tag} as the default (un-versioned) build${c.reset}`);
+      const wt = mkdtempSync(join(tmpdir(), `tsdoc-default-`));
+      createdWorktrees.push(wt);
+      try {
+        execSync(`git -C "${SOURCE_REPO_ROOT}" worktree add --detach "${wt}" "${defaultV.tag}"`, { stdio: 'ignore' });
+        const wtEntries = ENTRY_POINTS_REL.map((rel) => join(wt, rel));
+        const wtTsconfig = TSCONFIG_REL ? join(wt, TSCONFIG_REL) : null;
+        buildOnce({ entryPoints: wtEntries, tsconfig: wtTsconfig, version: null });
+      } catch (err) {
+        log(`${c.gold}warn${c.reset} default-alias build failed: ${err.message}`);
+      }
+    }
+  }
+} finally {
+  cleanup();
+}
+
+log('');
+log(`${c.dim}Sidebar wiring (astro.config.mjs):${c.reset}`);
+log(`${c.dim}  { label: 'TS API', autogenerate: { directory: '${cfg.outputDir.replace(/^src\/content\/docs\/?/, '')}' } }${c.reset}`);
+if (versions) log(`${c.dim}  → with ${versions.length} version${versions.length === 1 ? '' : 's'}, the sidebar auto-groups by version subdirectory.${c.reset}`);
+log('');

package/template/scripts/python-autodoc.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "Configuration for scripts/build-python-docs.mjs. Adjust to point at your Python source.",
+  "searchPath": "../../python-example/src",
+  "modules": [
+    "example_module"
+  ],
+  "outputDir": "src/content/docs/api",
+  "repoUrl": "",
+  "repoBranch": "main"
+}

package/template/scripts/ts-autodoc.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "Configuration for scripts/build-ts-docs.mjs. Adjust to point at your TypeScript project.",
+  "entryPoints": ["../../packages/your-lib/src/index.ts"],
+  "tsconfig": "../../packages/your-lib/tsconfig.json",
+  "outputDir": "src/content/docs/api/ts",
+  "githubPages": false,
+  "skipErrorChecking": true,
+  "repoUrl": "",
+  "repoBranch": "main"
+}

package/template/src/assets/README.md

@@ -0,0 +1 @@
+# Place your project's logo (PNG or SVG) in this folder, then reference it from astro.config.mjs and src/content/docs/index.mdx.

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

@@ -0,0 +1,81 @@
+---
+title: Your Project Docs
+description: Replace this with your project's elevator pitch — one sentence that tells visitors what you do.
+template: splash
+hero:
+  tagline: One-sentence tagline. Drop your hook here. The skill will offer to update this on first interaction.
+  actions:
+    - text: Get Started
+      link: /quickstart/
+      icon: right-arrow
+      variant: primary
+    - text: View Source
+      link: https://github.com/your-org/your-repo
+      icon: external
+      variant: secondary
+---
+
+import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
+import Glitch from '@abstractdata/starlight-theme/components/Glitch.astro';
+
+## <Glitch text="WHAT'S INSIDE" />
+
+Four cards is a starting point — replace, reorder, add more. Each `Card` accepts a `title`, an `icon` (any [Lucide icon](https://lucide.dev) name), and Markdown body content.
+
+<CardGrid>
+  <Card title="Quickstart" icon="rocket">
+    The five-minute install + first deploy walkthrough. [Read it →](/quickstart/)
+  </Card>
+  <Card title="API Reference" icon="open-book">
+    Auto-generated from your source's docstrings (Python today; TypeScript and OpenAPI coming). Run `bun run docs:python`.
+  </Card>
+  <Card title="Brand toggle" icon="setting">
+    Two motion modes: `full` (HUD) for marketing-y docs, `calm` for prose-heavy client docs. Light + dark in both. Configure in `astro.config.mjs`.
+  </Card>
+  <Card title="Branded components" icon="puzzle">
+    `<Glitch>`, `<Hero>`, branded callouts, and a Shiki theme that paints code in cyan / gold / burgundy. Import from `@abstractdata/starlight-theme/components/*`.
+  </Card>
+</CardGrid>
+
+## Make it yours
+
+Open Claude Code (or Cursor) in this folder — it'll greet you and offer to wire up Python autodoc, your sidebar, and your plugin config in one conversation. Or do it manually:
+
+<CardGrid>
+  <LinkCard
+    title="Edit astro.config.mjs"
+    description="Set your project title, sidebar structure, social links, and which motion mode the brand runs in."
+    href="/quickstart/#configure"
+  />
+  <LinkCard
+    title="Drop your logo"
+    description="Place it in src/assets/, then point logo.src in astro.config.mjs at it."
+    href="/quickstart/#logo"
+  />
+  <LinkCard
+    title="Write content"
+    description="Markdown and MDX in src/content/docs/. Sub-folders become sidebar groups."
+    href="/quickstart/#content"
+  />
+  <LinkCard
+    title="Deploy"
+    description="GitHub Pages workflow is preconfigured. Vercel and Cloudflare workflow variants ship alongside."
+    href="/quickstart/#deploy"
+  />
+</CardGrid>
+
+## Branded callouts
+
+The four standard Starlight callouts (`note`, `tip`, `caution`, `danger`) are styled with the brand palette — colored left border, matching glow in HUD mode, branded label typography.
+
+:::tip[Pro tip]
+Use `:::caution` for footguns, `:::danger` for destructive operations, `:::note` for context, `:::tip` for opinion. Your readers will thank you.
+:::
+
+:::caution[Heads up]
+Update the placeholder values in `astro.config.mjs` (title, site URL, social links) before deploying. The skill's first-interaction handshake catches these — open your AI assistant if you'd like it to do the rewrite for you.
+:::
+
+---
+
+> Replace this whole page once your real content lands. The `template: splash` frontmatter is what gives this hero its layout; switch to `template: doc` (or remove the line) on inner pages so they get a sidebar and table of contents.

package/template/src/content/docs/quickstart.md

@@ -0,0 +1,162 @@
+---
+title: Quickstart
+description: Five minutes from clean checkout to a deployed branded docs site.
+---
+
+This template gives you a Starlight documentation site pre-wired with the [Abstract Data Documentation Theme](https://github.com/Abstract-Data/abstract-data-doc-theme). This page is the hands-on walkthrough — copy it, replace the placeholders, ship it.
+
+## Install
+
+```bash
+bun install
+bun dev
+```
+
+That boots the dev server at `http://localhost:4321` with hot module reload. Edit any `.md`/`.mdx` file under `src/content/docs/` and the page updates instantly.
+
+:::tip
+If you don't have Bun yet: `curl -fsSL https://bun.sh/install | bash`. The theme is designed for Bun (faster installs, native TypeScript) but works on `npm` and `pnpm` too if your team prefers.
+:::
+
+## Configure
+
+Open `astro.config.mjs` and replace the placeholders:
+
+```js {3-5,12,18-19}
+starlight({
+  // ⬇️ project metadata
+  title: 'Your Project Docs',
+  description: 'One-sentence elevator pitch.',
+  site: 'https://your-deployed-url.example.com',
+
+  // ⬇️ uncomment for a logo
+  // logo: { src: './src/assets/your-logo.png', replacesTitle: true },
+
+  social: [
+    {
+      icon: 'github',
+      href: 'https://github.com/your-org/your-repo',
+      label: 'GitHub',
+    },
+  ],
+
+  plugins: [
+    abstractData({
+      motion: 'calm',  // 'full' for HUD, 'calm' for client docs
+      credit: 'auto',  // 'hide' for white-label
+    }),
+  ],
+});
+```
+
+The three knobs that matter most:
+
+- **`motion`** — `full` is the loud HUD look (marketing-y, animated hex grid, glitch on the version chip); `calm` strips animations while keeping palette and fonts. Default: `calm` for client work.
+- **`credit`** — `auto` shows "Built by Abstract Data" in the footer; `hide` removes it for white-label projects.
+- **`version`** *(optional)* — set to a string like `'v1.0.0'` to display a version chip in the header next to the social icons.
+
+## Add your logo
+
+Drop a PNG or SVG in `src/assets/` (e.g. `your-logo.png`), then in `astro.config.mjs`:
+
+```js
+logo: {
+  src: './src/assets/your-logo.png',
+  replacesTitle: true,  // hide the text title when logo is present
+}
+```
+
+The theme's `<Hero>` component uses Astro's `<Image>` for optimized output (lazy loading, AVIF/WebP, srcset). Drop a `400×400` or larger source — Astro handles the rest.
+
+## Write content
+
+Pages live under `src/content/docs/`:
+
+```
+src/content/docs/
+├── index.mdx           # the splash page (this file is its sibling)
+├── quickstart.md       # this page
+└── guides/             # subfolders become sidebar groups (with autogenerate)
+    ├── deployment.md
+    └── customization.md
+```
+
+Frontmatter sets the page title and description. Body is Markdown or MDX (Markdown + components):
+
+```md
+---
+title: My Page
+description: Short SEO description.
+---
+
+# Heading auto-rendered by Starlight
+
+Markdown content with **bold**, *italic*, [links](/), and `inline code`.
+```
+
+The theme's branded components are importable in any `.mdx` file:
+
+```mdx
+import Glitch from '@abstractdata/starlight-theme/components/Glitch.astro';
+
+# <Glitch text="404" /> Not Found
+```
+
+## Add API reference
+
+The template ships two autodoc pipelines — pick the one(s) that match your source. The `abstract-data-setup` workflow can detect your stack and prune this section automatically; if you'd rather drive it manually, follow whichever subsection applies.
+
+<!-- abstract-data-setup:python-autodoc -->
+
+### Python source
+
+```bash
+bun run docs:python
+```
+
+Reads `scripts/python-autodoc.json`, generates Markdown pages under `src/content/docs/api/` from your module docstrings via `pydoc-markdown`. Edit the config to point `searchPath` at your Python source root and list the `modules` you want documented.
+
+:::caution
+You need `pydoc-markdown` installed in your local Python environment: `pipx install pydoc-markdown` or `pip install --user pydoc-markdown`.
+:::
+
+<!-- /abstract-data-setup:python-autodoc -->
+
+<!-- abstract-data-setup:ts-autodoc -->
+
+### TypeScript source
+
+```bash
+bun run docs:ts
+```
+
+Reads `scripts/ts-autodoc.json`, generates Markdown pages under `src/content/docs/api/ts/` from your TSDoc comments via TypeDoc + `typedoc-plugin-markdown`. Point `entryPoints` at the entry TS files and `tsconfig` at the matching tsconfig.
+
+:::caution
+Install once as dev deps: `bun add -d typedoc typedoc-plugin-markdown`.
+:::
+
+<!-- /abstract-data-setup:ts-autodoc -->
+
+:::tip[Guided setup]
+Open Claude Code or Cursor in this folder and say *"set up docs"* — the bundled `abstract-data-setup` workflow detects your stack(s), audits docstring coverage, asks which modules to document, writes the configs, and tailors this very page so only the relevant autodoc subsection remains.
+:::
+
+## Deploy
+
+Three workflow files ship in `.github/workflows/`:
+
+| File | Target | When to use |
+|---|---|---|
+| `deploy.yml` | GitHub Pages | Default. Just enable Pages → "GitHub Actions" in repo settings and push. |
+| `deploy-vercel.yml` | Vercel | Opt-in. Add `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` secrets; run once. |
+| `deploy-cloudflare.yml` | Cloudflare Pages | Opt-in. Add `CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`. |
+
+For Vercel and Cloudflare, the simpler path is connecting the repo through their respective dashboards (no workflow file needed) — they auto-detect Astro and deploy on push. Use the workflow files only when you want CI to control deploys.
+
+## What's next
+
+- Iterate on `index.mdx` — the splash page is your shop window.
+- Add per-section guides under `src/content/docs/guides/`.
+- Run `bun run build && bun run preview` before deploying to catch errors with production assets.
+- Open Claude Code or Cursor in this folder if you want a guided setup — the bundled `abstract-data-setup` workflow handles the boilerplate.

package/template/src/content.config.ts

@@ -0,0 +1,46 @@
+import { defineCollection, z } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+/**
+ * Type-safe frontmatter for the docs collection.
+ *
+ * `docsSchema({ extend })` lets you add custom fields on top of Starlight's
+ * built-in ones (`title`, `description`, `sidebar`, `draft`, `pagefind`, …).
+ * The fields below are scaffolding — keep, replace, or extend them to match
+ * how your team actually tags content. Errors in frontmatter fail the build
+ * with helpful Zod messages, so this catches issues at PR time instead of
+ * after deploy.
+ *
+ * Common fields teams add:
+ *   - `category`: a grouping label for filterable views or future analytics
+ *   - `audience`: who this page is written for
+ *   - `lastReviewed`: when a maintainer last vetted the content (good for
+ *     surfacing "this page is over a year old" warnings)
+ */
+export const collections = {
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: z.object({
+        // ── User-authored fields ───────────────────────────────────
+        category: z.string().optional(),
+        audience: z
+          .enum(['user', 'contributor', 'maintainer'])
+          .optional(),
+        lastReviewed: z.coerce.date().optional(),
+
+        // ── Theme-managed fields ───────────────────────────────────
+        // Written by the autodoc orchestrators (build-python-docs.mjs /
+        // build-ts-docs.mjs) onto every page emitted under a `versions[]`
+        // tag. The bundled <VersionPicker> reads them via
+        // getCollection('docs') so the autodoc JSON stays the canonical
+        // source of truth — no duplicating the version list in your
+        // override component. Don't hand-edit these.
+        version: z.string().optional(),
+        versionLabel: z.string().optional(),
+        versionDefault: z.boolean().optional(),
+      }),
+    }),
+  }),
+};

package/template/src/env.d.ts

@@ -0,0 +1,2 @@
+/// <reference path="../.astro/types.d.ts" />
+/// <reference types="@abstractdata/starlight-theme/types" />

package/template/tsconfig.json

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