Getting started

Cookbook requires Node.js 22.19 or newer.

npm create @tenphi/cookbook@latest my-docs -- --yes
cd my-docs
npm run dev

The creator writes a README, Astro configuration, and docs.config.ts, then installs dependencies. It also writes AGENTS.md with instructions for coding agents. Edit README.md to change the home page. Add docs/guide.md to create /guide. New and edited pages appear in the development server without a restart.

Run this from your repository root:

npm create @tenphi/cookbook@latest docs-site -- --source . --yes
cd docs-site
npm run dev

The generated docs.config.ts points back to your repository. Your root README becomes the home page and docs/**/*.{md,mdx} supplies the other pages. Cookbook reads those files without copying or rewriting them.

Use --no-install to generate files before installing dependencies. The creator refuses to overwrite a non-empty destination in non-interactive mode.

npm create @tenphi/cookbook@latest my-package-docs -- \
  --package @scope/package@latest --yes
cd my-package-docs
npm run dev

The creator discovers documentation inside the actual published artifact and writes its exact version and integrity to cookbook.lock.json. Commit this file. The documented package is not installed and its lifecycle scripts do not run. Run npm run update when you want to resolve the requested tag or range again.

Cookbook requires Astro’s output: "static" setting. If your project uses output: "server", create a separate static Astro project for its documentation.

npx astro add @tenphi/cookbook

Your Astro configuration needs one integration:

import { defineConfig } from "astro/config";
import cookbook from "@tenphi/cookbook";

export default defineConfig({ integrations: [cookbook()] });

Cookbook includes its Astro renderer and discovers docs.config.ts automatically. With no documentation configuration, it uses README/docs conventions.

Start with the complete brand, logo, and font recipes. For deeper style changes or new components, read the customization rules. These rules and upstream references are also included in the installed Cookbook package.

Create docs.config.ts next to astro.config.ts:

import { defineDocsConfig } from "@tenphi/cookbook/config";

export default defineDocsConfig({
  site: {
    title: "Example Project",
    description: "Documentation for Example Project",
    repository: "https://github.com/example/project",
  },
  theme: {
    brand: { from: "#2f5bff" },
    fonts: { body: "Inter", heading: "Newsreader" },
  },
});

Change theme.fonts to use Google Fonts by name or your own font files. Use theme.presets for typography details, theme.styles for built-in elements, and defineComponent() with theme.customStyles to add a new element. The theme guide gives the starting path; the component styles reference lists every customizable sub-element.

The integration and CLI load the same configuration. Supported filenames are docs.config.ts, .mts, .js, and .mjs, in that order. An explicit integration config object takes precedence; configFile: false disables discovery. Use cookbook({ configFile: "./config/manual.ts" }) and cookbook doctor --config ./config/manual.ts for a nonstandard location.

An app in apps/docs/ can use repository content with:

import { defineDocsConfig } from "@tenphi/cookbook/config";

export default defineDocsConfig({ root: "../.." });

root is relative to the documentation configuration file. It controls content, local assets, and cookbook.lock.json. Run npm run doctor from the app directory; it resolves the same repository root as the integration. Individual sources can also declare their own roots for multi-package sites.

npm run validate
npm run preview

See working examples, authoring components, the AI agent workflow, and deployment. Existing users should read the version-specific upgrade guide.

For a complete configuration to adapt, start with the recipes. If validation fails, see troubleshooting.