| name | documentation-workflow |
| description | Use when adding or updating massCode documentation, documenting a new feature, changing docs website pages, adding docs assets, updating the VitePress sidebar, or adding README feature mentions. |
Documentation Workflow
Overview
Документация massCode живёт в VitePress сайте в docs/website/documentation. README — это общий обзор проекта, а не источник детального описания фич.
Documentation Surfaces
- Документация фич:
docs/website/documentation/**
- Sidebar документации:
docs/website/.vitepress/config.mts
- Assets документации:
docs/website/public/**
- Overview документации:
docs/website/documentation/index.md
- Overview проекта:
README.md
Core Rules
- Проверяй поведение фичи в коде или существующей документации; не документируй по памяти.
- Используй
rg, чтобы найти связанные страницы, скриншоты, shortcuts, labels и существующие формулировки.
- Если целевая версия известна, используй именно её. Если версия неизвестна, не придумывай её.
- Пользовательская документация сайта пишется на английском, в стиле существующих docs pages.
- Добавляй или обновляй наиболее конкретную страницу в
docs/website/documentation.
- Для новых страниц используй frontmatter с
title и description.
- Если фича доступна только с конкретного релиза, добавляй
<AppVersion text=">=x.y" /> ближе к началу страницы.
- Добавляй страницу в
docs/website/.vitepress/config.mts только если она должна появиться в навигации.
- Ссылайся из
docs/website/documentation/index.md только на широкие, cross-cutting фичи.
- Пиши короткими task-oriented секциями. Предпочитай пользовательские флоу, а не детали реализации.
- Shortcuts документируй через
<kbd>...</kbd> и указывай macOS плюс Windows/Linux варианты, если они отличаются.
VitePress Markdown Gotchas
- VitePress компилирует markdown как Vue-компонент, поэтому
{{ ... }} трактуется как Vue-интерполяция и исчезает из вывода.
- Fenced-блоки (
```) защищены автоматически — внутри них {{var}} рендерится буквально.
- Инлайн-код в backticks НЕ защищён:
`{{variables}}` отрендерится пустым. Чтобы вывести литеральные двойные фигурные скобки в тексте или таблице, оборачивай в v-pre:
<code v-pre>{{variables}}</code>
- Это же касается любых других Vue-конструкций (
{{ }}, директивы) в произвольном тексте страницы.
Images And Assets Rules
- Картинки для docs клади в
docs/website/public.
- Ссылайся на картинки через
withBase, например:
<img :src="withBase('/feature.png')">
- Если страница использует
withBase, добавь соответствующий script block:
import { withBase } from 'vitepress'
- Используй скриншоты только когда они реально объясняют фичу. Не добавляй декоративные изображения.
README Rules
- Добавляй README-упоминания только для user-facing фич, которые важны на уровне общего обзора проекта.
- Держи README copy коротким и product-level; подробное использование должно быть в
docs/website/documentation.
- Не пиши в README, когда фича была добавлена. Version availability должна жить в docs pages или release notes.
- Не ставь новую фичу первой автоматически. Сохраняй текущую информационную архитектуру: сначала основные spaces/features, затем широкие workflow helpers, если пользователь не попросил иначе.
Validation
- Запускай
git diff --check.
- Для изменений docs website запускай
pnpm -C docs/website build.
- Если нужно форматирование, ограничивай его изменёнными файлами и избегай широкого churn в config-файлах.
- Не коммить без явной просьбы пользователя. Для commit или PR загружай
github-workflow.
Common Mistakes
- Добавлять README-only документацию для фичи, которой нужна настоящая docs page.
- Забывать VitePress sidebar для новой страницы, которая должна быть в навигации.
- Добавлять version availability в README.
- Документировать shortcuts или поведение без проверки реализации.
- Запускать широкие formatters, которые переписывают существующий стиль docs config.
- Писать литеральные
{{ ... }} в инлайн-коде без v-pre — VitePress съест их как Vue-интерполяцию.
