Начало работы

Для Cookbook требуется Node.js 22.19 или новее.

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. Новые и изменённые страницы появляются на сервере разработки без перезапуска.

Выполните команды из корня репозитория:

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 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 output: "static". Если проект использует output: "server", создайте отдельный статический проект Astro для документации.

npx astro add @tenphi/cookbook

В конфигурации Astro нужна одна интеграция:

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

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

Cookbook включает собственный рендерер Astro и автоматически находит docs.config.ts. Без конфигурации документации он следует соглашениям для README и каталога docs/.

Начните с готовых рецептов для фирменного стиля, логотипа и шрифтов. Более глубокие изменения стилей и создание компонентов описаны в правилах настройки. Эти правила и ссылки на первоисточники также входят в установленный пакет Cookbook.

Создайте docs.config.ts рядом с 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" },
  },
});

В theme.fonts можно указать Google Fonts по имени или собственные файлы шрифтов. Для типографики используйте theme.presets, для встроенных элементов — theme.styles, а для новых элементов — defineComponent() вместе с theme.customStyles. Начните с руководства по теме; все настраиваемые части перечислены в справочнике стилей компонентов.

Интеграция и CLI загружают одну и ту же конфигурацию. Поддерживаются docs.config.ts, .mts, .js и .mjs именно в таком порядке. Явный объект config в интеграции имеет приоритет; configFile: false отключает обнаружение файла. Для нестандартного расположения используйте cookbook({ configFile: "./config/manual.ts" }) и cookbook doctor --config ./config/manual.ts.

Приложение в apps/docs/ может использовать материалы всего репозитория:

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

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

Значение root указывается относительно файла конфигурации документации. Оно определяет расположение контента, локальных ресурсов и cookbook.lock.json. Запустите npm run doctor из каталога приложения: команда найдёт тот же корень, что и интеграция. Для сайта с несколькими пакетами каждый источник также может задать свой корень.

npm run validate
npm run preview

Остальные руководства пока доступны на английском языке: примеры, компоненты для авторов, работа с ИИ-агентами, развёртывание и обновление между версиями. Для полной конфигурации начните с рецептов. Если проверка завершилась ошибкой, см. решение проблем.