@tenphi/cookbook 0.20.4 → 0.21.0

package/docs/ru/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`. Добавьте этот файл в Git. Документируемый пакет не устанавливается, а его скрипты не запускаются. Выполните `npm run update`, когда понадобится заново определить версию по указанному тегу или диапазону.
+
+## Добавьте Cookbook в существующий проект 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.
+
+Создайте `docs.config.ts` рядом с `astro.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-agents.md), [развёртывание](../deployment.md) и [обновление между версиями](../migration.md). Для полной конфигурации начните с [рецептов](../recipes.md). Если проверка завершилась ошибкой, см. [решение проблем](../troubleshooting.md).

package/docs/ru/index.md

@@ -0,0 +1,61 @@
+---
+title: Cookbook
+description: Создайте статический сайт документации на Astro из файлов репозитория или опубликованного npm-пакета и настройте его оформление под свой продукт.
+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: /ru/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), или [добавить Cookbook в проект Astro](./getting-started.md).
+
+## Этот сайт служит примером
+
+Текущая страница находится в [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.
+
+## Изучите руководство
+
+* [Начало работы](./getting-started.md): репозитории, npm-пакеты и существующие проекты Astro.
+* [Сравнение инструментов](../comparison.md): модель контента и настройки Cookbook.
+* [Примеры](../examples.md): репозитории, монорепозитории, пакеты и общие темы.
+* [Поиск и навигация](../site-navigation.md): как читатели находят страницы.
+* [Подготовка материалов](../authoring.mdx): страницы, компоненты и интерактивные примеры.
+* [Тема и компоненты](../theme-and-components.md): фирменный стиль, токены, шрифты и собственные компоненты.
+* [Развёртывание](../deployment.md): проверка и статический хостинг.
+
+Остальная документация пока доступна на английском языке. Также см. [работу с ИИ-агентами](../ai-agents.md), [справочник конфигурации](../configuration.md), [настройки публикации](../publishing.md) и [справочник CLI](../cli.md).

package/docs/site-navigation.md

@@ -0,0 +1,77 @@
+---
+title: Search and navigation
+description: Help readers find pages with search, sections, page contents, languages, and versions.
+---
+
+Cookbook builds routes from your content sources. With no explicit navigation,
+it lists published pages from those sources. Add `navigation.items` to choose
+their order and groups, or `navigation.tabs` to give major sections separate
+sidebars. The [navigation reference](./configuration.md#navigation) covers every
+item form and the rules for nested groups and tabs.
+
+For example, a small site can give its guide and API reference separate
+sidebars. Create pages at each tab's `link` route first:
+
+```ts
+navigation: {
+  tabs: [
+    { label: "Guide", link: "/", items: ["/", "/getting-started"] },
+    { label: "API", link: "/api", items: ["/api", "/api/client"] },
+  ],
+}
+```
+
+## Search
+
+The production build creates a local Pagefind index. Readers can select Search
+in the header or press Ctrl+K (⌘+K on macOS). The dialog focuses its input,
+shows matching pages and headings, and closes with Escape or its close button.
+Focus returns to the control that opened it. Search assets load when the dialog
+opens. During `astro dev`, the dialog explains that results require a build;
+use `npm run build && npm run preview` to test them.
+
+Search is enabled by default. Set `search.enabled: false` when the site does
+not need an index. Set `pagefind: false` in a published page's frontmatter to
+omit just that page. Draft pages are always omitted from search, even though
+their direct URLs remain available. The [publishing guide](./publishing.md)
+explains how preview indexing and draft visibility work.
+
+## Sections and page order
+
+Use groups for a short, scannable sidebar. A group may link to its own overview
+page; deeper groups expand to show their children. Cookbook checks that every
+internal navigation route exists. The order also sets previous and next page
+links. Tabs give each major section its own sidebar, including pages outside
+the tab's URL prefix when listed in that tab's `items`.
+
+Top-level groups keep their headings and direct links visible. Deeper groups
+open on click or keyboard activation, and the current page's ancestors open on
+arrival. A linked group header selects its page before toggling when that page
+is already selected. Explicit expansion choices are remembered for the browser
+tab. Only the current page is highlighted.
+
+On narrow screens, the active sidebar moves into a drawer. It includes the
+section selector, links, and a close control. The drawer closes when a reader
+follows a link. Keyboard focus stays in the drawer while it is open and returns
+to the menu control when it closes. Content and links remain readable if client
+JavaScript is unavailable.
+
+## Contents, languages, and versions
+
+Desktop articles show an on-page table of contents. Enable an optional compact
+contents list below the header on smaller screens with:
+
+```ts
+tableOfContents: { mobile: true, minHeadingLevel: 2, maxHeadingLevel: 3 }
+```
+
+The same field in page frontmatter overrides the site setting for that page;
+`tableOfContents: false` hides both lists. See [Authoring](./authoring.mdx#on-page-navigation)
+for heading behavior.
+
+Configure `locales` to offer translated pages and `site.versions` to offer
+documentation versions. The selectors prefer the equivalent page when it
+exists and fall back to a real language or version home when it does not.
+Only available translations appear in alternate-language metadata. See the
+[language](./configuration.md#languages) and
+[version](./configuration.md#site) configuration examples.