An [Astro](https://astro.build/) documentation theme with dark mode, interactive playgrounds, and SEO endpoints.
One integration call gives you a complete docs site: layout, navigation, table of contents, code highlighting,
LLM-friendly endpoints, and a library of interactive components.

- **Single integration**: rehype plugins, PostCSS, Shiki themes, sitemap, and SEO routes configured automatically
- **Dark mode**: three-state toggle (auto/light/dark) with View Transitions, no FOUC
- **Theming**: set `theme.hue` and `theme.saturation` in config; all colors derive via OKLch
- **Interactive playgrounds**: CodeMirror editor + sandboxed live preview with console capture
- **LLM endpoints**: `/llms.txt` and `/llms-full.txt` auto-generated from your markdown content
- **Bundled fonts**: Martian Grotesk + Martian Mono auto-injected (opt out with `fonts: false`)
- **Accessible**: roving focus, ARIA attributes, keyboard navigation throughout
- **Zero build step**: Astro resolves `.astro`/`.ts` source directly from the package

## Installation

Install the theme along with its peer dependencies:

Install `astro-pigment astro nanotags nanostores`:

- pnpm: `pnpm add astro-pigment astro nanotags nanostores`
- npm: `npm install astro-pigment astro nanotags nanostores`
- yarn: `yarn add astro-pigment astro nanotags nanostores`
- bun: `bun add astro-pigment astro nanotags nanostores`

## Quick Start

### 1. Configure the integration

```js
// astro.config.mjs
import { defineConfig } from "astro/config";
import docsTheme from "astro-pigment";

export default defineConfig({
  integrations: [
    docsTheme({
      project: {
        name: "my-project",
        description: "A short description of your project",
        license: {
          name: "MIT",
          url: "https://github.com/your-name/your-repo/blob/main/LICENSE",
        },
        github: { user: "your-name", repository: "your-repo" },
      },
      author: { name: "Your Name", url: "https://x.com/your_handle" },
      meta: { icon: "src/assets/icon.svg" },
      docs: {
        navLinks: [
          { href: "/", label: "Overview" },
          { href: "/api", label: "API" },
        ],
      },
    }),
  ],
});
```

### 2. Wire up the content collection

```ts
// src/content.config.ts
import { defineDocsCollections, defineMenuCollection } from "astro-pigment/content";

export const collections = {
  ...defineDocsCollections(),
  ...defineMenuCollection(),
};
```

Drop `.md`/`.mdx` files into `src/content/docs/`. The integration injects `/[...slug]` automatically — pages render with the layout, on-this-page rail, prev/next navigation, and edit-on-github link out of the box. To render pages yourself, set `docs.renderDefaultPage: false` and create your own `src/pages/[...slug].astro` (reuse `getDocsStaticPaths` from `astro-pigment/utils/content` to skip the boilerplate).

Each page declares `title`, `description`, and `order` in its frontmatter, plus optional `menu` and `toc` that decide its columns — see [Page frontmatter](/api/page-frontmatter). `defineMenuCollection()` above registers `src/content/menu/`, where a [menu](/api/menu-collection) is the reusable section nav a page opts into with `menu: "<menu id>"`; skip it if you don't need one.

Dark mode, sticky header, mobile popovers, code copy buttons, favicons, webmanifest, sitemap, LLM endpoints, and footer are all wired up automatically.

### 3. Pick theme colors (optional)

Temporarily enable the theme picker to dial in hue and saturation for your site:

```js
docsTheme({
  // ...your config
  themePicker: true, // shows a hue + saturation picker on the page
});
```

Drag the hue ring and saturation slider, pick values you like, then set them in config and remove `themePicker`:

```js
docsTheme({
  // ...your config
  theme: { hue: 135, saturation: 70 }, // the values you picked
});
```

### 4. Serve markdown to AI agents (recommended)

If your host runs edge middleware, add a one-line entry file so agents that request a page get its `.md` twin at the same URL — a `200` with `Content-Type: text/markdown`, no client redirect. Vercel, Netlify, Cloudflare Pages, and custom Node/Bun servers are each supported — see [Negotiating markdown for AI agents](/api/markdown-for-agents) in the API reference for the per-host setup.