@abstractdata/create-docs 0.2.3

package/template/.github/workflows/deploy-cloudflare.yml

@@ -0,0 +1,50 @@
+name: Deploy to Cloudflare Pages
+
+# Optional. Cloudflare Pages can also auto-deploy from a connected Git repo
+# (no workflow needed). Use this only if you want CI to control the deploy.
+#
+# Setup:
+#   1. Create a Cloudflare API token with "Cloudflare Pages — Edit" permission
+#      at dash.cloudflare.com/profile/api-tokens
+#   2. Add two GitHub secrets:
+#      - CLOUDFLARE_API_TOKEN
+#      - CLOUDFLARE_ACCOUNT_ID
+#   3. Set the project name below (line: projectName).
+#   4. Delete .github/workflows/deploy.yml if you're not using GitHub Pages.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  deployments: write
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build site
+        run: bun run build
+
+      - name: Publish to Cloudflare Pages
+        uses: cloudflare/pages-action@v1
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          projectName: your-project-name # ← change to your CF Pages project name
+          directory: dist
+          gitHubToken: ${{ secrets.GITHUB_TOKEN }}

package/template/.github/workflows/deploy-vercel.yml

@@ -0,0 +1,47 @@
+name: Deploy to Vercel
+
+# Optional. Most teams just connect their Git repo to Vercel and let Vercel
+# auto-deploy on push (no workflow needed). Use this only if you want CI to
+# control the deploy — for example, to gate behind a typecheck/lint step.
+#
+# Setup:
+#   1. Install Vercel CLI in this repo: `bun add -d vercel`
+#   2. Run `vercel link` once locally to attach the project.
+#   3. Add three GitHub secrets:
+#      - VERCEL_TOKEN     (from vercel.com/account/tokens)
+#      - VERCEL_ORG_ID    (from .vercel/project.json after link)
+#      - VERCEL_PROJECT_ID (from .vercel/project.json after link)
+#   4. Delete .github/workflows/deploy.yml (the GitHub Pages workflow) if you're not using Pages.
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Pull Vercel environment
+        run: bunx vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Build for Vercel
+        run: bunx vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Deploy
+        run: bunx vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

package/template/.github/workflows/deploy.yml

@@ -0,0 +1,55 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build site
+        run: bun run build
+        env:
+          # Astro reads `BASE_URL` if you've set `base:` in astro.config.mjs
+          # for project pages. Set it here to match.
+          BASE_URL: ${{ vars.BASE_URL || '/' }}
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    name: Deploy
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/template/CLAUDE.md

@@ -0,0 +1,46 @@
+# Abstract Data Documentation Theme — agent context
+
+This project uses the **Abstract Data Documentation Theme** (built on Astro Starlight, distributed as `@abstractdata/starlight-theme`). When talking to the user, refer to the product as the **"Abstract Data Documentation Theme"** — not "Astro Starlight" — Starlight is the substrate, not the product identity.
+
+## First-interaction handshake — IMPORTANT
+
+When you open a conversation in this project, immediately check the setup state:
+
+- **`scripts/python-autodoc.json`** — does it have placeholder values like `searchPath: "../../../python-example/src"` and a `modules` list pointing at `example_module`? Or has it been customized for this project's actual Python source?
+- **`astro.config.mjs`** — is `title: 'Your Project Docs'` still the literal placeholder? Is `site: 'https://example.com'` still the placeholder URL?
+
+**If either signal looks like a fresh scaffold,** open the conversation with this offer (don't wait for the user to ask):
+
+> "Looks like this is a freshly scaffolded Abstract Data Documentation Theme project. Want me to run the `abstract-data-setup` workflow now? It'll detect your Python source, audit docstring coverage, sniff your docstring style, ask a few config questions, and wire up `python-autodoc.json`, `astro.config.mjs`, and `package.json`. (Reply 'no' if you'd rather configure manually — I won't ask again.)"
+
+If the user agrees, immediately invoke the `abstract-data-setup` skill (`.claude/skills/abstract-data-setup/SKILL.md`).
+
+**If setup looks already-done** (JSON has real module names, `astro.config.mjs` has a real title): don't auto-offer the handshake. Just be a normal helpful assistant for whatever the user wants to work on.
+
+**Once the user has declined or completed setup:** treat this handshake as satisfied for the rest of the conversation. Don't keep nagging.
+
+## Skill location
+
+The full setup workflow lives at `.claude/skills/abstract-data-setup/SKILL.md`. It's an 11-phase procedural skill: confirm context → locate source → detect Python signals → audit docstring coverage → detect docstring style → recommend modules → gather brand config → write configs → optionally run docs:python → optional pre-commit hook → summary.
+
+## Project conventions
+
+- **Package manager: Bun** — not npm/yarn/pnpm. Use `bun run <name>` and `bun add <pkg>`.
+- **Commits: Conventional Commits** — release-please reads them to bump versions automatically. `feat:` for minor, `fix:` for patch, `feat!:` or `BREAKING CHANGE:` for major.
+- **Don't hand-edit:** `.cursor/rules/abstract-data-setup.mdc`, `.github/copilot-instructions.md`, `.cursor/rules/welcome.mdc` — these are auto-generated.
+
+## Quick reference
+
+- `astro.config.mjs` — Starlight config: title, sidebar, plugin options
+- `scripts/python-autodoc.json` — Python autodoc target config
+- `scripts/build-python-docs.mjs` — orchestrator that wraps pydoc-markdown
+- `src/content/docs/` — Markdown/MDX content
+- `bun run dev` — start the docs dev server
+- `bun run docs:python` — regenerate API pages from Python source
+- `bun run build` — production build
+
+## Links
+
+- Source repo: https://github.com/Abstract-Data/abstract-data-doc-theme
+- Theme on npm: https://www.npmjs.com/package/@abstractdata/starlight-theme
+- Scaffolder on npm: https://www.npmjs.com/package/@abstractdata/create-docs

package/template/README.md

@@ -0,0 +1,75 @@
+# Abstract Data Docs Template
+
+Starter Starlight documentation site with the [`@abstractdata/starlight-theme`](https://github.com/Abstract-Data/abstract-data-doc-theme) already wired in.
+
+## Use this template
+
+**The fastest path** — use the `@abstractdata/create-docs` CLI:
+
+```bash
+bun create @abstractdata/docs my-docs
+cd my-docs
+bun install
+bun dev
+```
+
+The CLI copies this template into a fresh folder, swaps `workspace:*` for a real published version of the theme, sets your project name in `package.json` and `astro.config.mjs`, and runs `git init` so you have a clean history from step zero.
+
+**Alternative — clone manually:**
+
+Click **"Use this template"** on the GitHub repo (or fork it) to create a new repo from this code, then:
+
+```bash
+git clone https://github.com/your-org/your-new-repo.git
+cd your-new-repo
+bun install
+bun dev
+```
+
+> **If you copied this folder out of the monorepo manually**, change the `@abstractdata/starlight-theme` dependency in `package.json` from `"workspace:*"` to a real version like `"^0.3.0"` before running `bun install`.
+
+## Customize
+
+See [`src/content/docs/quickstart.md`](./src/content/docs/quickstart.md) — it walks through what to change in `astro.config.mjs`, where to drop your logo, and how to toggle motion / credit / version.
+
+### Auto-setup with your AI coding assistant
+
+This template ships the `abstract-data-setup` workflow in three formats so it works regardless of which AI assistant you use:
+
+| Tool | File | Fidelity |
+|---|---|---|
+| **Claude Code** | `.claude/skills/abstract-data-setup/SKILL.md` | full procedural workflow |
+| **Cursor** | `.cursor/rules/abstract-data-setup.mdc` | full procedural workflow |
+| **GitHub Copilot** | `.github/copilot-instructions.md` | static reference (Copilot can't natively run interactive prompts) |
+
+Open your tool of choice in this folder and say **"set up docs"** (or "wire up Python autodoc", "configure docs", "audit docstrings", etc.). The workflow detects your source project, audits docstring coverage, sniffs docstring style, asks a few configuration questions, and writes the right files (`scripts/python-autodoc.json`, `astro.config.mjs` sidebar + plugin config, `package.json` scripts).
+
+If you only use one tool, delete the other adapter folders — they're independent files.
+
+The Claude Code SKILL.md is the source of truth; the Cursor and Copilot files are auto-generated from it. (Edit the SKILL.md and run `bun run sync-skills` if you're working in the monorepo.)
+
+Round 1 covers Python projects. TypeScript, Next.js, TanStack, OpenAPI, and other detectors are planned for follow-up rounds.
+
+## Deploy to GitHub Pages
+
+The workflow at `.github/workflows/deploy.yml` is preconfigured. To enable:
+
+1. **Repo Settings → Pages → Source:** select **"GitHub Actions"**.
+2. **Push to `main`.** The workflow builds with Bun and publishes to Pages.
+3. **For project pages** (e.g. `username.github.io/your-repo`), uncomment the `base:` line in `astro.config.mjs` and set it to `/your-repo-name`.
+
+## Other deploy targets
+
+The output is plain static HTML — drop `dist/` on any host:
+
+- **Vercel** — easiest: connect the repo at vercel.com → New Project. Vercel auto-detects Astro and deploys on every push. No workflow needed. If you want CI control, use `.github/workflows/deploy-vercel.yml` (delete the GitHub Pages workflow first).
+- **Cloudflare Pages** — easiest: connect at dash.cloudflare.com/?to=/:account/pages → Create Project. Same flow as Vercel. If you want CI control, use `.github/workflows/deploy-cloudflare.yml`.
+- **Netlify** — same auto-deploy pattern. Drop a `netlify.toml` if you need to override.
+
+## Update the theme
+
+```bash
+bun update @abstractdata/starlight-theme
+```
+
+Bun pulls the latest minor/patch within your semver range. Major versions are opt-in.

package/template/astro.config.mjs

@@ -0,0 +1,69 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import abstractData from '@abstractdata/starlight-theme';
+import starlightLinksValidator from 'starlight-links-validator';
+
+// https://astro.build/config
+export default defineConfig({
+  // ⬇️ Set to your production URL before going live (sitemap depends on it).
+  site: 'https://example.com',
+
+  // ⬇️ Uncomment if deploying to a project page (e.g. github.io/<repo>/).
+  // base: '/your-repo-name',
+
+  integrations: [
+    starlight({
+      // ⬇️ Replace with your project name.
+      title: 'Your Project Docs',
+      description: 'Branded documentation by Abstract Data.',
+
+      // ⬇️ Replace with your logo. Place it in `src/assets/`.
+      // logo: { src: './src/assets/your-logo.png', replacesTitle: true },
+
+      // ⬇️ Replace or remove.
+      social: [
+        {
+          icon: 'github',
+          label: 'GitHub',
+          href: 'https://github.com/your-org/your-repo',
+        },
+      ],
+
+      // ⬇️ Show "Last updated" timestamps on every page (read from git).
+      //    Requires the repo to be a git checkout at build time.
+      lastUpdated: true,
+
+      // ⬇️ Show an "Edit page" link in the footer of every doc.
+      //    Uncomment and replace once your repo URL is final.
+      // editLink: {
+      //   baseUrl: 'https://github.com/your-org/your-repo/edit/main/',
+      // },
+
+      // ⬇️ Customize your sidebar.
+      sidebar: [
+        {
+          label: 'Get Started',
+          items: [
+            { label: 'Welcome', slug: 'index' },
+            { label: 'Quickstart', slug: 'quickstart' },
+          ],
+        },
+      ],
+
+      plugins: [
+        abstractData({
+          // 'full' = HUD with animations · 'calm' = no motion (recommended for client docs)
+          motion: 'calm',
+          // 'auto' = "Built by Abstract Data" credit visible · 'hide' = white-label
+          credit: 'auto',
+          // Optional version chip in the header. Omit to hide.
+          // version: 'v1.0.0',
+        }),
+        // Fails the build on broken internal links — run on every PR.
+        // Set `errorOnFallbackPages: false` if you only build a subset
+        // of locales in dev.
+        starlightLinksValidator(),
+      ],
+    }),
+  ],
+});

package/template/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@abstractdata/docs-template",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Abstract Data documentation template — clone this for new client doc projects.",
+  "type": "module",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro check && astro build",
+    "preview": "astro preview",
+    "typecheck": "astro check",
+    "docs:python": "node scripts/build-python-docs.mjs",
+    "docs:ts": "node scripts/build-ts-docs.mjs"
+  },
+  "dependencies": {
+    "@abstractdata/starlight-theme": "workspace:*",
+    "@astrojs/starlight": "~0.37.0",
+    "astro": "^5.10.0",
+    "sharp": "^0.33.5",
+    "starlight-links-validator": "^0.16.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/template/public/favicon.svg

@@ -0,0 +1,26 @@
+<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    @media (prefers-color-scheme: light) {
+      .background { fill: black; }
+      .foreground { fill: white; }
+    }
+    @media (prefers-color-scheme: dark) {
+      .background { fill: white; }
+      .foreground { fill: black; }
+    }
+  </style>
+  <g clip-path="url(#clip0_7960_43945)">
+    <rect class="background" width="180" height="180" rx="37" />
+    <g style="transform: scale(95%); transform-origin: center">
+      <path class="foreground"
+        d="M101.141 53H136.632C151.023 53 162.689 64.6662 162.689 79.0573V112.904H148.112V79.0573C148.112 78.7105 148.098 78.3662 148.072 78.0251L112.581 112.898C112.701 112.902 112.821 112.904 112.941 112.904H148.112V126.672H112.941C98.5504 126.672 86.5638 114.891 86.5638 100.5V66.7434H101.141V100.5C101.141 101.15 101.191 101.792 101.289 102.422L137.56 66.7816C137.255 66.7563 136.945 66.7434 136.632 66.7434H101.141V53Z" />
+      <path class="foreground"
+        d="M65.2926 124.136L14 66.7372H34.6355L64.7495 100.436V66.7372H80.1365V118.47C80.1365 126.278 70.4953 129.958 65.2926 124.136Z" />
+    </g>
+  </g>
+  <defs>
+    <clipPath id="clip0_7960_43945">
+      <rect width="180" height="180" fill="white" />
+    </clipPath>
+  </defs>
+</svg>