@tenphi/cookbook 0.20.4 → 0.21.0

package/docs/es/index.md

@@ -0,0 +1,61 @@
+---
+title: Cookbook
+description: Crea un sitio de documentación estático con Astro a partir de tu repositorio o de un paquete npm publicado, con un tema adaptado a tu producto.
+template: splash
+seo:
+  title: Cookbook — documentación junto al código y adaptada a tu producto
+hero:
+  title: Documentación que permanece junto al código.
+  tagline: Cookbook es un kit de herramientas de documentación para Astro. Convierte el Markdown de tu repositorio o un paquete npm publicado en un sitio estático con búsqueda, y adapta los colores, la tipografía y los componentes a tu producto.
+  image:
+    html: '<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="14" fill="currentColor"/><path fill="#fff" d="M14.8 16c6.7.2 12.3 2 16.7 5.4v28.4c-4.4-3.1-10-4.7-16.6-4.9a3 3 0 0 1-2.9-3V19a3 3 0 0 1 2.8-3Z"/><path fill="#fff" d="M49.2 16c-6.7.2-12.3 2-16.7 5.4v28.4c4.4-3.1 10-4.7 16.6-4.9a3 3 0 0 0 2.9-3V19a3 3 0 0 0-2.8-3Z"/></svg>'
+  actions:
+    - text: Empezar
+      link: /es/getting-started/
+      variant: primary
+    - text: Comparar herramientas (en inglés)
+      link: /comparison/
+      variant: secondary
+sidebar:
+  label: Introducción
+  order: 1
+---
+## Qué incluye
+
+* **Usa la documentación que ya tienes.** Lee Markdown, MDX y recursos locales directamente desde tu repositorio, o genera el sitio a partir de un paquete npm fijado por versión e integridad. [Fuentes de contenido](../content-sources.md).
+* **Genera una referencia de API.** Convierte una especificación OpenAPI local en un resumen con búsqueda y una página por operación, con parámetros, cuerpos de petición, respuestas y ejemplos. [Referencias OpenAPI](../content-sources.md#openapi-references).
+* **Búsqueda integrada.** Pagefind indexa las páginas y los encabezados localmente, con un atajo de teclado y recursos de búsqueda que se cargan cuando hacen falta. [Búsqueda](../site-navigation.md#search).
+* **Navegación para documentación que crece.** Organiza secciones con pestañas y barras laterales agrupadas, añade índices de página y enlaces anterior/siguiente, y ofrece un menú de navegación móvil. [Búsqueda y navegación](../site-navigation.md).
+* **Componentes para documentación técnica.** Usa pestañas, avisos, tarjetas, pasos, grupos de código, código resaltado con controles de copia y ejemplos interactivos aislados en MDX. [Componentes de contenido](../authoring.mdx).
+* **Un tema adaptado a tu producto.** Configura colores de marca, paletas semánticas, fuentes, tipografía y partes de componentes con [Tasty](../upstream/tasty/README.md) y [Glaze](../upstream/glaze/README.md). Los modos claro, oscuro y de alto contraste reciben CSS estático generado durante la compilación. [Tema y componentes](../theme-and-components.md).
+* **Idiomas y versiones.** Ofrece páginas traducidas y documentación versionada, con selectores que llevan a la página equivalente cuando existe. [Idiomas y versiones](../site-navigation.md#contents-languages-and-versions).
+* **Comprobaciones antes de publicar.** Detecta enlaces rotos, recursos ausentes, rutas duplicadas y navegación inválida con errores que señalan el archivo de origen. Publica HTML prerenderizado en cualquier alojamiento estático. [Comprobaciones de calidad](../quality-checks.md).
+* **Páginas listas para compartir y leer.** Publica URL canónicas, vistas previas para redes sociales, mapas del sitio, Markdown descargable y un índice `llms.txt` para agentes de programación. [Metadatos de publicación](../publishing.md).
+
+## Empieza con tu repositorio
+
+Ejecuta estos comandos en un proyecto que ya tenga un archivo `README.md` o un directorio `docs/`:
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+cd docs-site
+npm run dev
+```
+
+Cookbook lee los archivos donde ya están. También puedes [crear un sitio nuevo](./getting-started.md), [documentar exactamente los archivos publicados en npm](./getting-started.md) o [añadir Cookbook a un proyecto Astro](./getting-started.md).
+
+## Este sitio es el ejemplo
+
+Esta página procede de [docs/es/index.md](https://github.com/tenphi/cookbook/blob/main/docs/es/index.md). Una pequeña [aplicación Astro](https://github.com/tenphi/cookbook/tree/main/apps/reference) genera el sitio directamente desde el directorio `docs/` del repositorio. La navegación, la búsqueda, los controles de código, los enlaces de edición y las fechas de Git están disponibles para cualquier sitio Cookbook.
+
+## Explora la guía
+
+* [Primeros pasos](./getting-started.md) explica cómo empezar con repositorios, paquetes npm y proyectos Astro existentes.
+* [Comparación de herramientas](../comparison.md) describe el modelo de contenido y personalización de Cookbook.
+* [Ejemplos](../examples.md) muestran configuraciones para repositorios, monorepos, paquetes y temas compartidos.
+* [Búsqueda y navegación](../site-navigation.md) explica cómo encuentran los lectores las páginas.
+* [Redacción](../authoring.mdx) cubre páginas, componentes y ejemplos interactivos.
+* [Tema y componentes](../theme-and-components.md) introduce la marca y los tokens y enlaza con fuentes, estilos y componentes propios.
+* [Despliegue](../deployment.md) cubre la validación y el alojamiento estático.
+
+El resto de la documentación aún está disponible en inglés. Consulta también el [flujo para agentes de IA](../ai-agents.md), la [referencia de configuración](../configuration.md), las [opciones de publicación](../publishing.md) y la [referencia de la CLI](../cli.md).

package/docs/fonts-and-typography.md

@@ -0,0 +1,157 @@
+---
+title: Fonts and typography
+description: Load local or Google fonts and tune semantic Tasty typography presets.
+---
+Start with the [theme overview](./theme-and-components.md) for brand colors and
+design tokens. Cookbook configures font loading at build time and applies
+named presets to the rendered site.
+
+## Typography presets
+
+The built-in [typography presets](./upstream/tasty/docs/styles.md#preset) are
+`body`, `heading`, `h1` through `h6`, `navigation`, `small`, and `code`. Onest
+is self-hosted and used for body and heading text by default; JetBrains Mono is
+self-hosted for code.
+
+### Change font families
+
+Set `theme.fonts` to load fonts and apply them to the matching presets. A Google
+Fonts family needs only its name:
+
+```ts
+theme: {
+  fonts: {
+    body: "Inter",
+    heading: "Newsreader"
+  }
+}
+```
+
+The short form follows the regular and strong weights in your configured
+presets, including heading and custom preset references. It requests normal and
+italic styles, prefers a variable range, and falls back to real static weights
+when ranges are unavailable. A font without italics produces a build warning;
+choose another family or select only its supported styles. To control the
+request exactly, list weights or ascending variable ranges and styles. Google
+Fonts must support them; see the
+[Google Fonts CSS API](https://developers.google.com/fonts/docs/css2) for its
+available styles and weight syntax.
+
+```ts
+theme: {
+  fonts: {
+    body: { google: "Inter", weights: ["400 750"], styles: ["normal", "italic"] }
+  }
+}
+```
+
+For a font you own, put its files in `public/fonts/` and give Cookbook their
+public paths. Cookbook checks that each file exists during the build and adjusts
+its URL for the Astro `base` path. A variable font can cover a weight range;
+use separate entries for regular and italic files when needed:
+
+```ts
+theme: {
+  fonts: {
+    body: {
+      family: "Acme Sans",
+      files: [
+        { src: "/fonts/acme-sans.woff2", weight: "100 900" },
+        { src: "/fonts/acme-sans-italic.woff2", weight: "100 900", style: "italic" }
+      ]
+    }
+  }
+}
+```
+
+The `body` role also feeds navigation and small text. `heading` feeds `h1`
+through `h6`, while `code` covers code text. Each role has a system fallback.
+Cookbook emits font faces through Tasty with `font-display: swap`. Google CSS
+and font files are downloaded at build time and cached in
+`<Astro cacheDir>/cookbook-fonts`. Files are served from your own site's
+`_cookbook/fonts/` path by default, including the deployment base. Visitors make
+no Google Fonts requests. Existing local-file definitions keep working.
+
+```ts
+theme: {
+  fonts: { body: "Inter" },
+  fontLoading: {
+    google: "self-hosted", // or "remote" to keep Google's font CDN URLs
+    cache: "reuse",       // "refresh" to fetch again; "offline" to forbid network
+    display: "swap"       // also auto, block, fallback, optional
+  }
+}
+```
+
+The first build requires network access. Preserve the Astro cache between CI
+runs; `offline` fails with an actionable message when an entry is missing or
+corrupt. Cache entries are content-verified and keyed by the exact request.
+`refresh` deliberately updates them. For a fully checked-in font source, copy
+licensed files into `public/fonts/` and use the local form. Only `wght` and
+`ital` axes are requested; use local variable files and Tasty typography styles
+for other axes. Styles and weights that do not exist are rejected for explicit
+requests. For static fonts, browsers select their nearest real weight;
+intermediate weights require a variable font.
+
+Migration: name-only Google font configuration now downloads the required
+weights and italics and serves them locally. This increases the initial build's
+font downloads and removes visitors' external font dependency. Set
+`fontLoading.google: "remote"` to retain CDN delivery. Existing CSS-variable
+weights that cannot be resolved from presets require explicit `weights`.
+
+### Adjust presets
+
+Presets merge property-by-property, so changing size, weight, or line height
+does not require copying the rest of the preset. `theme.presets` takes precedence
+over `theme.fonts` for an explicitly set `fontFamily`:
+
+```ts
+theme: {
+  presets: {
+    body: {
+      boldFontWeight: 680
+    },
+    heading: {
+      fontWeight: 650,
+      boldFontWeight: 740
+    },
+    h1: {
+      fontSize: "3rem",
+      letterSpacing: "-0.02em"
+    },
+    code: { fontSize: "0.9rem" }
+  }
+}
+```
+
+For a system or already loaded font, set its CSS family directly with
+`theme.presets.<role>.fontFamily`. This does not load a font file. Additional
+named presets are available to custom MDX components.
+
+Heading presets reference the `heading` family and weights; body, navigation,
+and controls reference `body`. Semantic `strong` and `b` elements use Tasty's
+`strong` modifier, so their weight comes from the active preset's
+`boldFontWeight` instead of a separate element-specific value. `strong` is a
+reserved modifier keyword, not a named preset; the modifier-only form is
+equivalent to `inherit / strong`. Body text uses a regular `400` weight and
+neutral tracking, while
+headings use a medium `610` weight and progressively gentle negative tracking.
+The separate `720` heading bold weight keeps emphasized heading text distinct.
+Navigation uses a lighter `450` weight with `580` for the current sidebar page,
+while smaller group labels establish hierarchy without oversized bold text.
+Inactive sidebar links use `sidebar-text`, a slightly softer blend of `text-soft`
+and the surface. In high-contrast mode it matches `text-soft`. Set
+`theme.palette['sidebar-text']` to adjust that color without changing other
+secondary text, or `theme.styles.Sidebar.Control` to customize the control.
+See [Search and navigation](./site-navigation.md#sections-and-page-order)
+for sidebar group and disclosure behavior. Inline code scales to `0.875em`
+of its surrounding text, including smaller table text; code blocks keep the
+`code` preset size. Customize inline code through
+`theme.styles.MarkdownInlineCode`.
+
+Cookbook applies each semantic typography role through its complete Tasty
+`preset`, so configured fields such as `fontStyle` and `textTransform` are not
+silently omitted.
+
+The exported `DEFAULT_THEME_TOKENS` and `DEFAULT_TYPOGRAPHY_PRESETS` constants
+are useful when building a theme editor or presenting a reset action.

package/docs/getting-started.md

@@ -98,11 +98,12 @@ export default defineDocsConfig({
 });
 ```
 
-Change `theme.fonts` to use [Google Fonts by name or your own font files](./theme-and-components.md#change-font-families).
+Change `theme.fonts` to use [Google Fonts by name or your own font files](./fonts-and-typography.md#change-font-families).
 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](./theme-and-components.md) includes examples and the complete
-list of customizable sub-elements.
+[theme guide](./theme-and-components.md) gives the starting path; the
+[component styles reference](./component-styles.md) 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

package/docs/index.md

@@ -6,7 +6,7 @@ seo:
   title: Cookbook — docs that stay with the code and fit your product
 hero:
   title: Documentation that stays with the code.
-  tagline: Build a static Astro docs site from repository Markdown or a locked npm package, then shape its colors, typography, and components to fit your product.
+  tagline: Cookbook is an Astro documentation toolkit. Turn your repository Markdown or a published npm package into a searchable static site, with colors, typography, and components that fit your product.
   image:
     html: '<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="14" fill="currentColor"/><path fill="#fff" d="M14.8 16c6.7.2 12.3 2 16.7 5.4v28.4c-4.4-3.1-10-4.7-16.6-4.9a3 3 0 0 1-2.9-3V19a3 3 0 0 1 2.8-3Z"/><path fill="#fff" d="M49.2 16c-6.7.2-12.3 2-16.7 5.4v28.4c4.4-3.1 10-4.7 16.6-4.9a3 3 0 0 0 2.9-3V19a3 3 0 0 0-2.8-3Z"/></svg>'
   actions:
@@ -20,6 +20,37 @@ sidebar:
   label: Overview
   order: 1
 ---
+## What you get
+
+* **Use the docs you already have.** Read Markdown, MDX, and local assets
+  directly from your repository, or build from an npm package locked to an exact
+  version and integrity. [Content sources](./content-sources.md).
+* **Generate an API reference.** Turn a local OpenAPI spec into a searchable
+  overview and a page for each operation, with parameters, request bodies,
+  responses, and examples. [OpenAPI references](./content-sources.md#openapi-references).
+* **Search built in.** Pagefind indexes your pages and headings locally, with a
+  keyboard shortcut and search assets that load when needed.
+  [Search](./site-navigation.md#search).
+* **Navigation for growing docs.** Organize sections with tabs and grouped
+  sidebars, add page contents and previous/next links, and give mobile readers a
+  navigation drawer. [Search and navigation](./site-navigation.md).
+* **Components for technical writing.** Use tabs, callouts, cards, steps, code
+  groups, highlighted code with copy controls, and sandboxed interactive
+  previews in MDX. [Authoring components](./authoring.mdx).
+* **A theme that fits your product.** Configure brand colors, semantic palettes,
+  fonts, typography, and individual component parts through [Tasty](./upstream/tasty/README.md) and [Glaze](./upstream/glaze/README.md).
+  Light, dark, and high-contrast appearances receive static CSS generated at
+  build time. [Theme and components](./theme-and-components.md).
+* **Languages and versions.** Offer translated pages and versioned docs, with
+  selectors that take readers to the equivalent page when available.
+  [Languages and versions](./site-navigation.md#contents-languages-and-versions).
+* **Checks before you ship.** Catch broken links, missing assets, duplicate
+  routes, and invalid navigation with errors that point to the source. Publish
+  prerendered HTML to any static host. [Quality checks](./quality-checks.md).
+* **Pages ready to share and read.** Publish canonical URLs, social previews,
+  sitemaps, downloadable Markdown, and an `llms.txt` index for coding agents.
+  [Publishing metadata](./publishing.md).
+
 ## Start with your repository
 
 Run this from a project that already has a `README.md` or `docs/` directory:
@@ -42,29 +73,9 @@ The page you're reading comes from this repository's
 A small [Astro app](https://github.com/tenphi/cookbook/tree/main/apps/reference)
 builds directly from the root `docs/` directory. Its navigation, search, code
 controls, edit links, and Git timestamps are available to every Cookbook site.
-
-## Content and design on your terms
-
-### Keep the source where it belongs
-
-Use a repository's Markdown and local assets without copying them into an Astro
-content tree. Cookbook can also read OpenAPI specs or the documentation inside an
-npm artifact pinned to its exact version and integrity.
-[Explore content sources](./content-sources.md).
-
-### Shape the site through configuration
-
-Start with a brand color, then configure semantic palettes, fonts, typography,
-and named component parts through [Tasty](./upstream/tasty/README.md) and
-[Glaze](./upstream/glaze/README.md). Partial `theme.styles` overrides merge with
-Cookbook's defaults before CSS extraction, so the browser receives static CSS.
-[Explore the theme](./theme-and-components.md).
-
-### Catch drift before publishing
-
-Broken links, missing assets, duplicate routes, and invalid navigation fail with
-source-aware errors. The result is prerendered HTML with local search, ready for
-any static host. [See the validation workflow](./quality-checks.md).
+Use the language selector in the header to read this page and the getting-started
+guide in Spanish, Russian, Japanese, or Simplified Chinese. Other guides remain
+in English for now.
 
 ## Explore the guide
 
@@ -74,7 +85,10 @@ any static host. [See the validation workflow](./quality-checks.md).
   customization model alongside other options.
 * [Working examples](./examples.md) show repository, monorepo, package, and
   shared-theme configurations.
+* [Search and navigation](./site-navigation.md) explains how readers find pages.
 * [Authoring](./authoring.mdx) covers pages, components, and interactive examples.
+* [Theme and components](./theme-and-components.md) starts with brand and tokens,
+  then points to fonts, built-in styles, and custom components.
 * [Deployment](./deployment.md) covers validation and static hosting.
 
 For agent-assisted setup, see the [AI agent workflow](./ai-agents.md). The

package/docs/ja/getting-started.md

@@ -0,0 +1,109 @@
+---
+title: はじめに
+description: ドキュメントサイトの作成、既存リポジトリの文書化、公開済み npm パッケージの利用方法を説明します。
+sidebar:
+  order: 2
+---
+
+Cookbook には Node.js 22.19 以降が必要です。
+
+## 最初のサイトを作る
+
+```sh
+npm create @tenphi/cookbook@latest my-docs -- --yes
+cd my-docs
+npm run dev
+```
+
+作成ツールは README、Astro の設定、`docs.config.ts` を書き込み、依存パッケージをインストールします。コーディングエージェント向けの指示を記した `AGENTS.md` も作成します。ホームページを変えるには `README.md` を編集してください。`docs/guide.md` を追加すると `/guide` が作られます。新規・変更したページは、開発サーバーを再起動せずに反映されます。
+
+## 既存のリポジトリを文書化する
+
+リポジトリのルートで実行します。
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+cd docs-site
+npm run dev
+```
+
+生成された `docs.config.ts` は元のリポジトリを参照します。ルートの README がホームページになり、`docs/**/*.{md,mdx}` がほかのページになります。Cookbook はファイルをコピー・書き換えず、そのまま読み込みます。
+
+依存パッケージをインストールする前にファイルだけ作るには、`--no-install` を指定します。対話なしのモードでは、空でない保存先の上書きを拒否します。
+
+## 公開済みの npm パッケージを文書化する
+
+```sh
+npm create @tenphi/cookbook@latest my-package-docs -- \
+  --package @scope/package@latest --yes
+cd my-package-docs
+npm run dev
+```
+
+作成ツールは実際に公開されたパッケージからドキュメントを見つけ、正確なバージョンと整合性情報を `cookbook.lock.json` に記録します。このファイルをコミットしてください。対象パッケージはインストールされず、ライフサイクルスクリプトも実行されません。指定したタグやバージョン範囲を再解決したい場合は、`npm run update` を実行します。
+
+## 既存の Astro プロジェクトに追加する
+
+Cookbook では Astro の `output: "static"` が必要です。プロジェクトで `output: "server"` を使っている場合は、ドキュメント用に別の静的 Astro プロジェクトを作成してください。
+
+```sh
+npx astro add @tenphi/cookbook
+```
+
+Astro の設定に必要な統合は一つだけです。
+
+```ts
+import { defineConfig } from "astro/config";
+import cookbook from "@tenphi/cookbook";
+
+export default defineConfig({ integrations: [cookbook()] });
+```
+
+Cookbook には Astro 用レンダラーが含まれ、`docs.config.ts` を自動検出します。ドキュメント設定がない場合は、README と `docs/` の規約を使用します。
+
+## サイトを設定する
+
+まずは[ブランド、ロゴ、フォントのレシピ](../recipes.md)をご覧ください。より細かなスタイル変更や新しいコンポーネントには、[カスタマイズのルール](../customization-rules.md)を参照してください。これらのルールと参照先は、インストールされる Cookbook パッケージにも含まれます。
+
+`astro.config.ts` と同じ場所に `docs.config.ts` を作成します。
+
+```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" },
+  },
+});
+```
+
+`theme.fonts` を変更すると、[名前で指定する Google Fonts や独自のフォントファイル](../fonts-and-typography.md)を使えます。タイポグラフィの詳細には `theme.presets`、組み込み要素には `theme.styles`、新しい要素には `defineComponent()` と `theme.customStyles` を使用します。[テーマガイド](../theme-and-components.md)が出発点となり、[コンポーネントスタイルのリファレンス](../component-styles.md)にはカスタマイズ可能なすべてのパーツが載っています。
+
+統合と CLI は同じ設定を読み込みます。対応するファイル名は優先順に `docs.config.ts`、`.mts`、`.js`、`.mjs` です。統合に明示した `config` オブジェクトが優先され、`configFile: false` で自動検出を無効にできます。標準以外の場所では `cookbook({ configFile: "./config/manual.ts" })` と `cookbook doctor --config ./config/manual.ts` を使用してください。
+
+## モノレポのルート
+
+`apps/docs/` 内のアプリから、リポジトリ全体のコンテンツを利用できます。
+
+```ts
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({ root: "../.." });
+```
+
+`root` はドキュメント設定ファイルからの相対パスです。コンテンツ、ローカルアセット、`cookbook.lock.json` の場所を決めます。アプリのディレクトリで `npm run doctor` を実行すると、統合と同じリポジトリのルートが解決されます。複数パッケージを扱うサイトでは、ソースごとにルートを指定することもできます。
+
+## 検証して公開する
+
+```sh
+npm run validate
+npm run preview
+```
+
+ほかのガイドは現在英語で公開されています。[使用例](../examples.md)、[執筆用コンポーネント](../authoring.mdx)、[AI エージェントの作業手順](../ai-agents.md)、[デプロイ](../deployment.md)、[バージョン別のアップグレードガイド](../migration.md)を参照してください。設定例には[レシピ](../recipes.md)、検証に失敗した場合には[トラブルシューティング](../troubleshooting.md)が役立ちます。

package/docs/ja/index.md

@@ -0,0 +1,61 @@
+---
+title: Cookbook
+description: リポジトリや公開済み npm パッケージから、製品に合ったテーマの静的な Astro ドキュメントサイトを作成します。
+template: splash
+seo:
+  title: Cookbook — コードとともに保ち、製品に合わせて整えるドキュメント
+hero:
+  title: コードと同じ場所にあるドキュメント。
+  tagline: Cookbook は Astro 向けのドキュメントツールキットです。リポジトリの Markdown や公開済み npm パッケージを、検索できる静的サイトに変換し、色、タイポグラフィ、コンポーネントを製品に合わせて調整できます。
+  image:
+    html: '<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 64 64" aria-hidden="true"><rect width="64" height="64" rx="14" fill="currentColor"/><path fill="#fff" d="M14.8 16c6.7.2 12.3 2 16.7 5.4v28.4c-4.4-3.1-10-4.7-16.6-4.9a3 3 0 0 1-2.9-3V19a3 3 0 0 1 2.8-3Z"/><path fill="#fff" d="M49.2 16c-6.7.2-12.3 2-16.7 5.4v28.4c4.4-3.1 10-4.7 16.6-4.9a3 3 0 0 0 2.9-3V19a3 3 0 0 0-2.8-3Z"/></svg>'
+  actions:
+    - text: 使い始める
+      link: /ja/getting-started/
+      variant: primary
+    - text: ツールを比較（英語）
+      link: /comparison/
+      variant: secondary
+sidebar:
+  label: 概要
+  order: 1
+---
+## 主な機能
+
+* **既存のドキュメントをそのまま利用。** Markdown、MDX、ローカルアセットをリポジトリから直接読み込むか、バージョンと整合性を固定した npm パッケージからサイトを構築できます。[コンテンツソース](../content-sources.md)。
+* **API リファレンスを生成。** ローカルの OpenAPI 仕様から、検索可能な概要と操作ごとのページを作成します。パラメータ、リクエストボディ、レスポンス、例を掲載できます。[OpenAPI リファレンス](../content-sources.md#openapi-references)。
+* **検索を標準搭載。** Pagefind がページと見出しをローカルで索引化します。キーボードショートカットで検索を開き、検索用アセットは必要なときに読み込まれます。[検索](../site-navigation.md#search)。
+* **ドキュメントの成長に対応するナビゲーション。** タブやグループ化したサイドバーでセクションを整理し、ページ内目次、前後のページへのリンク、モバイル用のナビゲーションドロワーを提供できます。[検索とナビゲーション](../site-navigation.md)。
+* **技術文書用のコンポーネント。** MDX でタブ、注意書き、カード、手順、コードグループ、コピー操作付きのコードハイライト、隔離された対話的プレビューを使えます。[執筆用コンポーネント](../authoring.mdx)。
+* **製品に合ったテーマ。** [Tasty](../upstream/tasty/README.md) と [Glaze](../upstream/glaze/README.md) でブランドカラー、セマンティックなパレット、フォント、タイポグラフィ、コンポーネントの各パーツを設定できます。ライト、ダーク、高コントラストの各表示には、ビルド時に生成した静的 CSS が配信されます。[テーマとコンポーネント](../theme-and-components.md)。
+* **言語とバージョン。** 翻訳ページやバージョン別のドキュメントを提供できます。切り替え先に対応するページがあれば、そのページへ移動します。[言語とバージョン](../site-navigation.md#contents-languages-and-versions)。
+* **公開前の検証。** リンク切れ、アセットの欠落、重複したルート、無効なナビゲーションを、ソースの場所を示すエラーで検出します。事前生成した HTML は任意の静的ホストに公開できます。[品質チェック](../quality-checks.md)。
+* **共有しやすく、読み取りやすいページ。** 正規 URL、ソーシャルプレビュー、サイトマップ、ダウンロード用 Markdown、コーディングエージェント向けの `llms.txt` 索引を公開できます。[公開メタデータ](../publishing.md)。
+
+## リポジトリから始める
+
+`README.md` または `docs/` ディレクトリがあるプロジェクトで、次を実行します。
+
+```sh
+npm create @tenphi/cookbook@latest docs-site -- --source . --yes
+cd docs-site
+npm run dev
+```
+
+Cookbook はファイルを現在の場所から読み込みます。[新しいサイトを作る](./getting-started.md)、[npm に公開されたファイルをそのまま文書化する](./getting-started.md)、[既存の Astro プロジェクトに追加する](./getting-started.md)方法もあります。
+
+## このサイト自体が使用例
+
+このページの原稿は [docs/ja/index.md](https://github.com/tenphi/cookbook/blob/main/docs/ja/index.md) にあります。小さな [Astro アプリ](https://github.com/tenphi/cookbook/tree/main/apps/reference) が、リポジトリの `docs/` ディレクトリを直接読み込んでサイトを構築します。ナビゲーション、検索、コード操作、編集リンク、Git の更新日時は、どの Cookbook サイトでも利用できます。
+
+## ガイドを探す
+
+* [はじめに](./getting-started.md)：リポジトリ、npm パッケージ、既存の Astro プロジェクト。
+* [ドキュメントツールの比較](../comparison.md)：Cookbook のコンテンツとカスタマイズの考え方。
+* [使用例](../examples.md)：リポジトリ、モノレポ、パッケージ、共有テーマ。
+* [検索とナビゲーション](../site-navigation.md)：読者がページを見つける仕組み。
+* [執筆](../authoring.mdx)：ページ、コンポーネント、対話的な例。
+* [テーマとコンポーネント](../theme-and-components.md)：ブランド、トークン、フォント、組み込みスタイル、独自コンポーネント。
+* [デプロイ](../deployment.md)：検証と静的ホスティング。
+
+これ以外のドキュメントは現在英語で公開されています。[AI エージェント向けの手順](../ai-agents.md)、[設定リファレンス](../configuration.md)、[公開設定](../publishing.md)、[CLI リファレンス](../cli.md)も参照してください。

package/docs/migration.md

@@ -38,6 +38,42 @@ upgrade the site's Cookbook runtime or package-manager dependencies. Commit the
 documentation lock separately when intentionally updating imported content.
 Local Markdown needs no lock update.
 
+## Upcoming theme API cleanup
+
+Use canonical Glaze palette names throughout configuration and color
+references. Replace `theme.palette.textSoft` with `theme.palette["text-soft"]`
+and update any `base`, `target`, `bg`, or `fg` references to `"text-soft"`.
+Camel-case palette names now fail validation.
+
+The `colors` returned by `resolveColorTheme()` and `resolveDocsTheme()` also
+use canonical names: `surface-2`, `surface-3`, `text-soft`, `accent-text`,
+`accent-surface`, and `accent-surface-text`. Update property access to bracket
+notation, for example `theme.colors["accent-text"]`.
+
+Configure `theme.tokens` with `$name` keys, such as `$radius`. The old `--name`
+configuration keys now fail validation; the emitted CSS custom properties
+still use `--name`.
+
+Custom styles no longer target `data-tasty-anatomy` attributes automatically.
+For a custom component, use `defineComponent(name, options)`. For custom global
+rules, pass `resolveComponentStyles(name, baseStyles)` to `useGlobalStyles()`.
+Both merge `theme.customStyles[name]` into the complete base styles during
+server rendering. See [custom components](./custom-components.md).
+
+## 0.19.x to 0.20
+
+Cookbook 0.20 generates a themed social preview image when a site has no
+`site.seo.image`. If your host or sharing workflow expects a particular image,
+set that field explicitly; use `false` to publish without a site-wide image.
+Review [social preview configuration](./publishing.md#titles-and-social-previews)
+after upgrading.
+
+Cookbook requires a static Astro output. Adding it to an Astro project with
+`output: "server"` now reports that requirement directly; create a separate
+static documentation app for that case. Search and navigation received visual
+and interaction updates without a configuration migration. Review any custom
+`Search`, `SearchResults`, or header styles in a production preview.
+
 ## 0.18.x to 0.19
 
 Cookbook now renders documentation with its own Astro components. The public
@@ -54,7 +90,7 @@ and `Steps` components remain available.
 
 Renderer class names now use Cookbook-owned names. Update any custom CSS or
 scripts that target generated markup, and prefer the named `theme.styles`
-surfaces in the [theme reference](./theme-and-components.md).
+surfaces in [Component styles](./component-styles.md).
 
 The `plugins` integration option no longer forwards Starlight hooks. Move
 content transforms to Astro's `markdown` configuration and use
@@ -77,7 +113,7 @@ These changes were introduced in 0.18:
   self-hosts the files. The initial build requires network access. Preserve the
   Astro font cache for offline rebuilds, use local files for checked-in assets,
   or select `theme.fontLoading.google: "remote"` for CDN delivery. See
-  [fonts](./theme-and-components.md#change-font-families).
+  [fonts](./fonts-and-typography.md#change-font-families).
 - **Colors:** body tone 0 and heading tone 4 remain the reading defaults.
   The default logo uses fixed Glaze colors (`logo-surface` and `logo-mark`), so
   its book stays light in dark mode. Customize these independently of accents.
@@ -100,8 +136,8 @@ These changes were introduced in 0.18:
   browser scripts and `client:*` islands cannot import Cookbook styling, Tasty,
   or Glaze. Attach interaction scripts to the static markup. Isolated,
   sandboxed `Preview` content is the
-  documented exception. The new surface inventory is in the
-  [theme reference](./theme-and-components.md).
+  documented exception. The new surface inventory is in
+  [Component styles](./component-styles.md).
 - **Page text:** the footer offers copy/download Markdown by default. Set
   `site.seo.copyPage: false` to disable the controls and generated page files.
   Configure static host headers if raw Markdown must be excluded from indexing;

package/docs/plugins.md

@@ -91,8 +91,8 @@ available at `@tenphi/renderer/content` for renderer-only projects.
 
 Component overrides receive page data from `Astro.locals.cookbookRoute`,
 including the current entry, locale, navigation, table of contents, and head
-tags. See [theme and components](./theme-and-components.md) for Tasty styling
-and [configuration](./configuration.md) for structural overrides.
+tags. See [Custom components](./custom-components.md) for Tasty styling and
+[configuration](./configuration.md#components) for structural overrides.
 
 Use Astro's Markdown plugin APIs for content transforms, and Cookbook's graph
 and built-output checks for link validation. Extensions tied to another

package/docs/quality-checks.md

@@ -27,7 +27,7 @@ Repository contributors can run these checks after `pnpm build`:
 | `pnpm check:theming`         | Consumer components, colors, units, recipes, presets, overrides, and logos                   |
 | `pnpm check:fonts`           | Real Google variable/italic fonts, local fonts, and offline cache rebuild                    |
 | `pnpm check:plugins`         | Tested plugin contracts and actionable incompatibility failures                              |
-| `pnpm check:recipes`         | Extract, type-check, build, and validate documented configurations verbatim                  |
+| `pnpm check:recipes`         | Public anatomy inventory and build-checked examples                                          |
 | `pnpm check:authoring`       | Custom highlighting, code groups, mobile contents, hero images, and OpenAPI                  |
 | `pnpm check:browser`         | Chromium keyboard/focus, search, copy actions, appearance, mobile navigation, and axe checks |
 | `pnpm check:install`         | Clean installation and build from packed artifacts, including lint/type exports              |

package/docs/recipes.md

@@ -7,8 +7,8 @@ These are complete `docs.config.ts` files. Start with a generated Cookbook
 project, keep its `astro.config` integration, and replace the documentation
 configuration with one recipe. Add the files listed above each example.
 [Working examples](./examples.md) covers repository and npm source layouts;
-[configuration](./configuration.md) and the [theme reference](./theme-and-components.md)
-cover every option.
+[configuration](./configuration.md) lists the available fields, while the
+[theme guide](./theme-and-components.md) explains the customization path.
 
 The repository's `pnpm check:recipes` extracts the marked examples below and in
 Working examples verbatim, type-checks them, builds actual consumer sites, and
@@ -38,7 +38,33 @@ export default defineDocsConfig({
 
 The header token also covers the mobile sidebar close control. Copy buttons and
 page navigation keep the base radius. Built-in element overrides merge into the
-complete defaults. See the [named style anatomy](./theme-and-components.md).
+complete defaults. See the [named style anatomy](./component-styles.md).
+
+## Built-in component styles
+
+Supply only the properties you want to change. Cookbook merges these partial
+objects into the base style trees before extracting CSS. The example uses the
+current named parts of the Appearance panel and search input:
+
+```ts cookbook-verify=component-styles
+import { defineDocsConfig } from "@tenphi/cookbook/config";
+
+export default defineDocsConfig({
+  site: { title: "Acme docs" },
+  theme: {
+    brand: { from: "#315efb" },
+    styles: {
+      ThemeSelect: {
+        Trigger: { border: "#border-strong" },
+        Panel: { shadow: "0 1rem 3rem #shadow" },
+      },
+      SearchResults: { Input: { radius: "12px" } },
+    },
+  },
+});
+```
+
+Find all supported names in [Component styles](./component-styles.md).
 
 ## Local variable font
 
@@ -65,7 +91,7 @@ export default defineDocsConfig({
 
 For Google Fonts use `fonts: { body: "Inter", heading: "Newsreader" }` instead.
 Cookbook downloads and self-hosts the required weights and italics at build time.
-See [fonts](./theme-and-components.md#change-font-families) for caching,
+See [fonts](./fonts-and-typography.md#change-font-families) for caching,
 explicit ranges, styles, and remote delivery.
 
 ## English and French