docs-site

Documentation Site Management (Astro + Starlight)

Maintain documentation sites built with Astro and Starlight, deployed to GitHub Pages. This skill is generic — it reads .docs-config.json in the project root for all repo-specific details.

Before Any Docs Work

Always read .docs-config.json first. This file lives at CLAUDE_PROJECT_DIR/.docs-config.json and contains:

• site.directory — path to the Astro site root (e.g., site, docs)
• site.baseUrl — base path for deployed site (e.g., /my-project/)
• site.siteUrl — root URL of deployment target (e.g., https://user.github.io)
• site.contentDir — content directory relative to site root (typically src/content/docs)
• sections — sidebar sections with slug, label, and purpose
• sourceMappings — maps source files/globs to doc pages they inform
• terminology — canonical terms and their synonyms
• agentDocs — agent documentation configuration

If .docs-config.json does not exist, suggest running /docs-init to generate it before proceeding with any documentation work.

Astro + Starlight Fundamentals

• Astro is a static site generator. Starlight is its documentation theme.
• Content lives in <site.directory>/<site.contentDir>/ (read from .docs-config.json).
• Content collection is defined in src/content.config.ts using the standard Starlight docsLoader.
• The starlight-llms-txt plugin generates llms.txt, llms-full.txt, and llms-small.txt at build time from existing content pages.
• Built-in Starlight components: Card, CardGrid, LinkCard, Tabs, TabItem.
• Build: bun install && bunx astro build from the site directory.
• Dev server: bunx astro dev from the site directory.

Reading .docs-config.json

{
  "site": {
    "directory": "<path>",
    "baseUrl": "/<project>/",
    "siteUrl": "https://user.github.io",
    "contentDir": "src/content/docs"
  },
  "sections": [
    { "slug": "getting-started", "label": "Getting Started", "purpose": "..." }
  ],
  "sourceMappings": [
    { "source": "README.md", "docs": ["getting-started/overview"] }
  ],
  "terminology": { "ticket": ["card", "item", "task"] },
  "agentDocs": {
    "quickReferencePage": "reference/agent-quick-reference",
    "llmsSmallExcludes": ["reference/design-docs"]
  }
}

• sections — defines what sidebar sections exist and what content belongs in each.
• sourceMappings — declares which source files inform which doc pages. When editing a doc page, check the source files it maps to for accuracy. When a source file changes, the corresponding doc pages may need updating.
• terminology — canonical terms and synonyms. Always use the canonical term (the key) rather than any synonym (the values).
• agentDocs.quickReferencePage — slug for the AI Agent Quick Reference page.
• agentDocs.llmsSmallExcludes — section prefixes excluded from llms-small.txt.

Content Conventions

Page format

Pages are .md or .mdx files under the content directory.

Required frontmatter:

---
title: Page Title
description: One-line description for SEO and search
---

Optional Starlight frontmatter:

Field	Type	Description
sidebar.order	number	Position within sidebar group
sidebar.badge	string/object	Badge displayed next to sidebar entry
tableOfContents	boolean/object	Control table of contents display
template	string	splash for landing pages; doc (default) for all others

Landing pages

Landing pages use template: splash. All other pages use the default doc template.

Internal links

Internal links must include the base URL prefix from .docs-config.json. For a page at getting-started/overview with base URL /my-project/:

[See the overview](/my-project/getting-started/overview)

Do not add trailing slashes in source-level links — Astro handles this.

Sidebar Management

The sidebar is defined manually in astro.config.mjs — it is not autogenerated from directory structure.

Every new content page MUST have a corresponding entry in the sidebar config. Orphaned pages (in the content directory but not in the sidebar) are not discoverable by readers.

Sidebar structure mirrors the section slugs defined in .docs-config.json. Sidebar entries use slug (not link) pointing to the content path without file extension:

sidebar: [
  {
    label: 'Getting Started',
    items: [
      { label: 'Overview', slug: 'getting-started/overview' },
    ],
  },
],

Section Purposes

Read section purposes from the sections array in .docs-config.json. Each section has:

• slug — directory name under the content directory
• label — human-readable name for the sidebar
• purpose — description of what content belongs in this section

When creating new pages, match the page's content to the appropriate section's purpose. If no section fits, discuss with the user before creating a new section.

Source-of-Truth Relationships

The sourceMappings array in .docs-config.json connects source files to their documentation pages:

{
  "source": "src/lib/**/*.ts",
  "docs": ["reference/api"]
}

• source — a file path or glob pattern relative to the project root
• docs — doc page slugs that should reflect this source's content

When a source file changes, check if corresponding doc pages need updating. When editing a doc page, consult the source files it maps to for accuracy.

Bun-Everywhere Policy

All JavaScript/TypeScript tooling uses Bun exclusively. No npm, no npx, no Node-specific tooling.

Concern	Command
Install dependencies	bun install
Dev server	bunx astro dev
Build site	bunx astro build
Run scripts	bun run <script.ts>
Run tests	bun test

Writing Style

• Use second person ("you") for guides, third person for reference docs.
• Keep pages focused — one concept per page.
• Use tables for structured data.
• Use fenced code blocks with language tags for all examples.
• No trailing slashes in source-level links.
• Strict heading hierarchy — never skip levels (H1 → H3 is wrong; use H1 → H2 → H3).