@tenphi/cookbook 0.20.5 → 0.21.1

package/docs/component-styles.md

@@ -192,7 +192,7 @@ it stays complete when a surface changes.
 #### Search
 
 * `Search`: `Status`, `Dialog`, `CloseIcon`, `OpenDialog`, `EnteredDialog`, `Backdrop`, `EnteredBackdrop`, `Frame`, `Container`, `Close`, `HoverClose`, `ActiveClose`
-* `SearchResults`: `UI`, `Form`, `Drawer`, `Input`, `Clear`, `Results`, `Result`, `ResultLink`, `SearchIcon`, `ClearIcon`, `SuppressedClear`, `Message`, `List`, `Title`, `Excerpt`, `NestedResult`, `Match`, `More`, `HoverMore`
+* `SearchResults`: `UI`, `Form`, `Field`, `EngineControls`, `Drawer`, `Input`, `Clear`, `Results`, `Result`, `ResultLink`, `SearchIcon`, `ClearIcon`, `SuppressedClear`, `Message`, `List`, `Title`, `Excerpt`, `NestedResult`, `Match`, `More`, `HoverMore`
 
 <!-- component-anatomy:end -->
 
@@ -232,11 +232,10 @@ same.
 
 Register custom names and their partial Tasty objects in `theme.customStyles`.
 Built-in names belong in `theme.styles` and reject misspelled sub-elements.
-Custom names can also target a matching user-authored `data-tasty-anatomy` attribute.
 The name must match the string passed to `defineComponent()` or
-`resolveComponentStyles()`, or the `data-tasty-anatomy` value. A production
+`resolveComponentStyles()`. A production
 build warns when a configured custom name has no matching component style
-resolver or rendered anatomy attribute.
+resolver.
 
 The default renderer runs Tasty in Astro extract mode. Direct components and
 the remaining document/vendor bridge styles are collected into shared static
@@ -352,7 +351,8 @@ theme: {
 `Document` owns resets, base typography, generic controls, responsive media,
 and accessibility utilities. `MainPane` and `MainContent` own the content
 layout. `Markdown` owns prose, lists, links, quotations, and disclosure
-anatomy. `Search` owns the dialog; `SearchResults` owns the Pagefind UI.
+anatomy. `Search` owns the dialog; `SearchResults` owns the search field and
+Pagefind results UI.
 `MarkdownAlert` styles rendered alert blockquotes; `Card`, `Callout`, and
 `Steps` style Cookbook components.
 
@@ -393,7 +393,12 @@ it cannot access its parent's origin. Configure its size with
 using that directive, authored previews must use style blocks rather than style
 attributes.
 
-Search uses an owned, keyboard-accessible dialog with Pagefind's indexing and
-results UI. Its clear-button sizing is adapted to `SearchResults.Input` styles,
-so the browser does not need inline layout declarations. The adapter is checked
-against the pinned Pagefind UI version during builds.
+Search uses an owned, keyboard-accessible dialog and server-rendered input so
+the first opening can focus the field immediately on mobile. Pagefind's indexing
+and results UI load lazily. Customize the field with `SearchResults.Field`,
+`Input`, and `Clear`; `EngineControls` hides Pagefind's duplicate controls.
+Closing waits for the dialog's fade transition, with reduced motion respected.
+The fullscreen mobile dialog has no dimmed or blurred backdrop; the backdrop
+transition applies only to wider layouts.
+The Pagefind sizing adapter prevents inline layout declarations and is checked
+against the pinned UI version during builds.

package/docs/configuration.md

@@ -399,7 +399,7 @@ theme: {
       saturation: 0,
       contrast: { wcag: [7, 10] }
     },
-    textSoft: {
+    "text-soft": {
       base: "surface",
       tone: [25, 10],
       saturation: 0.05,

package/docs/custom-components.md

@@ -262,9 +262,7 @@ useGlobalStyles(
 ```
 
 `defineComponent` and `resolveComponentStyles` read the same `theme.customStyles`
-configuration; user configuration contains only the properties to change. They do not require a
-`data-tasty-anatomy` attribute. That attribute remains available for older
-components using the compatibility bridge described above.
+configuration; user configuration contains only the properties to change. Each custom style name must match a call to one of these helpers.
 
 ## Linting custom styles
 

package/docs/es/index.md

@@ -6,7 +6,7 @@ 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: Crea un sitio de documentación estático con Astro a partir de archivos Markdown de tu repositorio o de un paquete npm fijado, y adapta los colores, la tipografía y los componentes a tu producto.
+  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:
@@ -20,6 +20,18 @@ 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/`:
@@ -36,20 +48,6 @@ Cookbook lee los archivos donde ya están. También puedes [crear un sitio nuevo
 
 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.
 
-## Contenido y diseño a tu manera
-
-### Conserva los archivos en su lugar
-
-Usa los archivos Markdown y recursos locales de un repositorio sin copiarlos a un árbol de contenido de Astro. Cookbook también puede leer especificaciones OpenAPI o la documentación de un paquete npm fijado por versión e integridad. [Explora las fuentes de contenido](../content-sources.md).
-
-### Adapta el aspecto del sitio
-
-Empieza con un color de marca y configura paletas semánticas, fuentes, tipografía y partes de componentes mediante [Tasty](../upstream/tasty/README.md) y [Glaze](../upstream/glaze/README.md). Las personalizaciones parciales de `theme.styles` se combinan con los valores predeterminados de Cookbook antes de extraer el CSS. El navegador recibe CSS estático. [Explora el tema](../theme-and-components.md).
-
-### Detecta problemas antes de publicar
-
-Los enlaces rotos, recursos ausentes, rutas duplicadas y errores de navegación detienen la validación con mensajes que indican el archivo de origen. El resultado es HTML prerenderizado con búsqueda local, listo para cualquier alojamiento estático. [Consulta el flujo de validación](../quality-checks.md).
-
 ## Explora la guía
 
 * [Primeros pasos](./getting-started.md) explica cómo empezar con repositorios, paquetes npm y proyectos Astro existentes.

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:
@@ -46,29 +77,6 @@ Use the language selector in the header to read this page and the getting-starte
 guide in Spanish, Russian, Japanese, or Simplified Chinese. Other guides remain
 in English for now.
 
-## 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).
-
 ## Explore the guide
 
 * [Getting started](./getting-started.md) covers repositories, npm packages, and

package/docs/ja/index.md

@@ -6,7 +6,7 @@ seo:
   title: Cookbook — コードとともに保ち、製品に合わせて整えるドキュメント
 hero:
   title: コードと同じ場所にあるドキュメント。
-  tagline: リポジトリの Markdown やバージョンを固定した npm パッケージから静的な Astro ドキュメントサイトを作成し、色、タイポグラフィ、コンポーネントを製品に合わせて調整できます。
+  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:
@@ -20,6 +20,18 @@ 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/` ディレクトリがあるプロジェクトで、次を実行します。
@@ -36,20 +48,6 @@ Cookbook はファイルを現在の場所から読み込みます。[新しい
 
 このページの原稿は [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 サイトでも利用できます。
 
-## コンテンツもデザインも自由に
-
-### ソースファイルをそのまま使う
-
-リポジトリの Markdown とローカルアセットを、Astro のコンテンツツリーへコピーせずに利用できます。OpenAPI 仕様や、バージョンと整合性を固定した npm パッケージ内のドキュメントも読み込めます。[コンテンツソースを見る](../content-sources.md)。
-
-### 製品に合わせて外観を整える
-
-ブランドカラーから始め、[Tasty](../upstream/tasty/README.md) と [Glaze](../upstream/glaze/README.md) でセマンティックなパレット、フォント、タイポグラフィ、コンポーネントの名前付きパーツを設定できます。`theme.styles` の部分的な上書きは、CSS の抽出前に Cookbook の既定値と統合されます。ブラウザには静的な CSS が届きます。[テーマを見る](../theme-and-components.md)。
-
-### 公開前に問題を検出する
-
-リンク切れ、アセットの欠落、重複したルート、無効なナビゲーションは、原因となるソースファイルを示すエラーになります。出力はローカル検索を備えた事前生成 HTML で、どの静的ホストにも配置できます。[検証の流れを見る](../quality-checks.md)。
-
 ## ガイドを探す
 
 * [はじめに](./getting-started.md)：リポジトリ、npm パッケージ、既存の Astro プロジェクト。

package/docs/migration.md

@@ -38,6 +38,28 @@ 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

package/docs/ru/index.md

@@ -6,7 +6,7 @@ seo:
   title: Cookbook — документация рядом с кодом и в стиле вашего продукта
 hero:
   title: Документация рядом с кодом.
-  tagline: Создайте статический сайт документации на Astro из Markdown-файлов репозитория или зафиксированного npm-пакета, а затем настройте цвета, типографику и компоненты под свой продукт.
+  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:
@@ -20,6 +20,18 @@ 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/`:
@@ -36,20 +48,6 @@ Cookbook читает файлы на их текущем месте. Вы та
 
 Текущая страница находится в [docs/ru/index.md](https://github.com/tenphi/cookbook/blob/main/docs/ru/index.md). Небольшое [приложение Astro](https://github.com/tenphi/cookbook/tree/main/apps/reference) собирает сайт прямо из каталога `docs/` в репозитории. Навигация, поиск, элементы управления кодом, ссылки на редактирование и даты из Git доступны любому сайту Cookbook.
 
-## Ваши материалы и оформление
-
-### Храните исходные файлы там, где им место
-
-Используйте Markdown-файлы и локальные ресурсы репозитория без копирования в дерево контента Astro. Cookbook также умеет читать спецификации OpenAPI и документацию npm-пакета, зафиксированного по версии и контрольной сумме. [Подробнее об источниках контента](../content-sources.md).
-
-### Настройте сайт под свой продукт
-
-Начните с фирменного цвета, затем настройте семантические палитры, шрифты, типографику и именованные части компонентов с помощью [Tasty](../upstream/tasty/README.md) и [Glaze](../upstream/glaze/README.md). Частичные переопределения `theme.styles` объединяются со стандартными стилями Cookbook до извлечения CSS. В браузер отправляется статический CSS. [Подробнее о теме](../theme-and-components.md).
-
-### Находите ошибки до публикации
-
-Неработающие ссылки, отсутствующие ресурсы, дублирующиеся маршруты и неверная навигация вызывают ошибки с указанием исходного файла. Результат — предварительно созданный HTML с локальным поиском, готовый для любого статического хостинга. [Посмотрите порядок проверки](../quality-checks.md).
-
 ## Изучите руководство
 
 * [Начало работы](./getting-started.md): репозитории, npm-пакеты и существующие проекты Astro.

package/docs/theme-and-components.md

@@ -84,7 +84,7 @@ theme: {
       saturation: 0,
       contrast: { wcag: [7, 10] }
     },
-    textSoft: {
+    "text-soft": {
       base: "surface",
       tone: [25, 10],
       saturation: 0.05,
@@ -101,7 +101,7 @@ the second applies to high contrast. Use absolute tones for reading text:
 `text` starts at tone 0 and `heading` at tone 4, giving headings only a slight
 reduction in contrast. Glaze applies its tone boundaries in normal mode, so
 body text is not pure black, then inverts the tones for dark mode. High-contrast
-mode uses the full range. `textSoft` is reserved for secondary text.
+mode uses the full range. `text-soft` is reserved for secondary text.
 `heading` follows an explicitly configured `text` declaration unless it has
 its own declaration, preserving existing custom palettes.
 Contrast requirements are minimum safeguards: Glaze preserves the authored
@@ -168,8 +168,8 @@ high-contrast modes. Configuration diagnostics and rendering use the same graph.
 Missing references and cycles fail with the color name; layered configurations
 resolve references after merging.
 
-`textSoft` remains an alias for `text-soft`. Use either spelling, but do not
-configure both. The names `current`, `constructor`, and `prototype` are reserved.
+Palette names use lowercase letters, digits, and hyphens, such as `text-soft`.
+The names `current`, `constructor`, and `prototype` are reserved.
 Declaring a built-in name intentionally overrides that role; use a project
 prefix for additional roles to avoid future naming collisions.
 
@@ -218,7 +218,7 @@ directly to Tasty `#name` tokens. `COOKBOOK_PALETTE_NAMES`, exported from
 | Area                | Roles                                                                                                                                                                                                           |
 | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Surfaces            | `surface`, `header`, `overlay`, `surface-2`, `surface-3`, `surface-2-hover`, `surface-2-pressed`, `surface-3-hover`, `surface-3-pressed`                                                                        |
-| Reading             | `text`, `heading`, `text-soft` (alias `textSoft`), `text-muted`, `sidebar-text`                                                                                                                                 |
+| Reading             | `text`, `heading`, `text-soft`, `text-muted`, `sidebar-text`                                                                                                                                                    |
 | Brand and focus     | `accent-text`, `accent-surface`, `accent-surface-text`, `accent-surface-subtle`, `accent-surface-2-subtle`, `logo-surface`, `logo-mark`, `focus`                                                                |
 | Borders and effects | `border`, `border-strong`, `shadow`, `clear`                                                                                                                                                                    |
 | Status              | `info`, `success`, `warning`, `danger`, each with `-text` and `-surface` variants                                                                                                                               |
@@ -258,8 +258,7 @@ check does not replace keyboard, screen-reader, and rendered-page testing.
 
 Token names follow Tasty's
 [token and unit syntax](./upstream/tasty/docs/dsl.md#built-in-units): `$name`
-becomes the CSS custom property `--name`. Existing `--name` keys are still
-accepted for compatibility.
+becomes the CSS custom property `--name`. Configure tokens with `$name` keys.
 
 ```ts
 theme: {

package/docs/zh/index.md

@@ -6,7 +6,7 @@ seo:
   title: Cookbook — 与代码保持同步、契合产品风格的文档
 hero:
   title: 与代码放在一起的文档。
-  tagline: 使用仓库中的 Markdown 或锁定版本的 npm 包创建静态 Astro 文档站点，再根据产品调整颜色、字体排版和组件。
+  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:
@@ -20,6 +20,18 @@ 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)。
+* **便于分享和读取的页面。** 发布规范网址、社交预览、站点地图、可下载的 Markdown，以及供编程智能体使用的 `llms.txt` 索引。[发布元数据](../publishing.md)。
+
 ## 从你的仓库开始
 
 在已有 `README.md` 或 `docs/` 目录的项目中运行：
@@ -36,20 +48,6 @@ Cookbook 会直接读取原位置的文件。你也可以[创建新站点](./get
 
 你正在阅读的页面来自 [docs/zh/index.md](https://github.com/tenphi/cookbook/blob/main/docs/zh/index.md)。一个小型 [Astro 应用](https://github.com/tenphi/cookbook/tree/main/apps/reference) 直接从仓库根目录的 `docs/` 构建站点。导航、搜索、代码操作、编辑链接和 Git 更新时间都可用于任何 Cookbook 站点。
 
-## 内容与设计由你决定
-
-### 让源文件留在原处
-
-直接使用仓库中的 Markdown 和本地资源，无须复制到 Astro 内容目录。Cookbook 还可以读取 OpenAPI 规范，或读取已锁定版本和完整性校验值的 npm 包中的文档。[了解内容来源](../content-sources.md)。
-
-### 调整站点外观
-
-从品牌颜色入手，再通过 [Tasty](../upstream/tasty/README.md) 和 [Glaze](../upstream/glaze/README.md) 配置语义色板、字体、排版以及组件的命名部分。`theme.styles` 中的局部覆盖会在提取 CSS 前与 Cookbook 的默认样式合并，浏览器只会收到静态 CSS。[了解主题](../theme-and-components.md)。
-
-### 在发布前发现问题
-
-无效链接、缺失资源、重复路由和错误的导航配置会产生包含源文件位置的错误。生成结果是带有本地搜索功能的预渲染 HTML，可部署到任意静态托管服务。[查看验证流程](../quality-checks.md)。
-
 ## 浏览指南
 
 * [入门](./getting-started.md)：仓库、npm 包和现有 Astro 项目的使用方法。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenphi/cookbook",
-  "version": "0.20.5",
+  "version": "0.21.1",
   "description": "Repository-native static documentation for Astro",
   "type": "module",
   "keywords": [
@@ -68,8 +68,8 @@
   "author": "Andrey Yamanov",
   "license": "MIT",
   "dependencies": {
-    "@tenphi/docs": "0.20.5",
-    "@tenphi/renderer": "0.20.5"
+    "@tenphi/docs": "0.21.1",
+    "@tenphi/renderer": "0.21.1"
   },
   "peerDependencies": {
     "astro": "^7.3.2"