Написание документации

Сайт собран на Astro Starlight 0.37 и плагине starlight-theme-nova. Страницы лежат под apps/docs/src/content/docs/ и написаны в .mdx. Цель этой страницы — держать новые вклады визуально и структурно консистентными с тем, что уже есть.

Расположение файлов и форма URL

apps/docs/src/content/docs/
├── guide/             → /guide/...
├── recipes/           → /recipes/...
├── api/               → /api/...
├── packages/          → /packages/...
├── migration/         → /migration/...
├── ecosystem/         → /ecosystem/...
└── contributing/      → /contributing/...

Имена файлов в kebab-case (from-useeffect.mdx, notification-pipeline.mdx). URL’ы совпадают с именем файла без расширения, в нижнем регистре, с trailing slash.
Перекрёстные ссылки абсолютные и в kebab-case: /api/react/use-event/, /guide/essentials/conditions/, /packages/codemod/.
Никаких ведущих или хвостовых пробелов в slug’ах; никаких подчёркиваний.

Frontmatter

У каждой страницы есть как минимум title и description. Используй двойные кавычки — особенно если значение начинается с @ (иначе YAML разберёт его как алиас):

---
title: "@triggery/core"
description: "The framework-agnostic orchestration runtime."
sidebar:
  order: 1
---

sidebar.order управляет позицией, когда сайдбар autogenerate-ится. Меньшие числа идут раньше.

Что куда идёт

Раздел	Аудитория	Стиль
Guide	Читатель учит библиотеку сверху вниз	Длинная объяснительная проза. Ментальные модели, зачем, когда не стоит. Примеры иллюстративные.
Recipes	Читатель копирует рабочий сценарий	Сценарий сначала. Полный исполняемый код. End-to-end, включая тест.
API Reference	Читатель смотрит сигнатуру	Лаконично. Сигнатура → параметры → возвращаемое значение → пример → see-also.
Migration	Читатель тащит багаж (useEffect/saga/RxJS)	Таблица соответствий → пары до/после → пометка про codemod.
Packages	Читатель выбирает пакет	Установка → «что внутри» → быстрый пример → связанное.
Ecosystem	Читатель ищет адаптеры/интеграции	Таблицы пакетов с однострочными описаниями и ссылками.
Contributing	Читатель пишет PR	Конвенции, не нарратив.

Если не уверен, куда положить страницу — выбирай раздел, чья аудитория совпадает с ментальным состоянием читателя в этот момент, а не с темой.

Компоненты

Перечисленные ниже компоненты импортируются из @astrojs/starlight/components и используются по всему сайту консистентно. Импортируй их в верху файла, под frontmatter:

import { Aside, LinkCard, CardGrid, TabItem, Steps, FileTree } from '@astrojs/starlight/components';

Компонент	Когда применять
`<Aside type="tip">` / `"caution"` / `"note"` / `"danger"`	Боковые врезки. Не злоупотребляй — переизбыток превращается в шум.
`<LinkCard title=… description=… href=… />`	Перекрёстные ссылки в конце страницы.
`<CardGrid>`	Оборачивает 2-4 `<LinkCard>` в подвале страницы.
`<TabItem label=…>` (внутри `<FrameworkTabs>`) и `<PackageManagers pkg=…>`	Переключение между React/Solid/Vue или pnpm/npm/yarn/bun.
`<Steps>`	Нумерованный упорядоченный список с сильным визуальным акцентом.
`<FileTree>`	Рендер листинга директорий — используй для секций «где живёт этот файл».

Стилевые правила

Никакого H1. Заголовок страницы берётся из frontmatter; первый заголовок в теле — ##.
Никаких хвостовых «## Summary» — заканчивай страницу <CardGrid> с карточками следующих шагов.
Никаких эмодзи в заголовках, теле или коммит-сообщениях.
Никакого маркетингового антуража — никаких «🚀 What’s new», «✨ Features». Простые заголовки секций.
Блоки кода несут title=-префикс с путём к файлу, если представляют реальный файл:
```
```ts title="src/triggers/message.trigger.ts"
```
```
Используй fenced code с явными тегами языка. Никаких тильд.
Таблицы — GFM pipe-таблицы. Выравнивание держи свободным — люди не grep’ают по нему.

Внутренний голос

Обращайся к читателю на «ты». Избегай «мы», кроме коллективных утверждений проекта («мы поставляем codemod-скрипты для брейкингов»).
Прямо, технично, без воды. Цель — плотность Zod и приветливость Vue.
Покажи код, затем объясни что поменялось и почему. Избегай «давайте я объясню».
Честно о пределах — «это не маппится» / «запланировано на 1.0» / «используй X вместо» лучше, чем расплывчатые обещания.

Проверка изменений

cd apps/docs
pnpm dev               # http://localhost:4321/triggery/
pnpm --filter @triggery/docs build

Сборка запускает чекер ссылок и генератор i18n-фолбэков. Сломанные внутренние ссылки роняют сборку — чини их локально до пуша.

Настройка окружения Клонировать, установить, запустить документацию локально.

Стандарты кода TypeScript strict, именование, только ESM.

RFC-процесс Когда правке доков нужен RFC (редко).

Кодекс поведения Будь крут к окружающим.