Про эту документацию
Как она устроена и что делать, чтобы она не протухла.
Правило разделения
README — про репозиторий. Этот сайт — про приложение. Каждый факт живёт ровно в одном месте.
В README остаются только команды, дерево src/ и ссылка сюда. Всё остальное — здесь. Если вы ловите себя на том, что пишете один и тот же факт дважды, значит одно из мест лишнее.
У некоторых чисел есть страница-владелец. Пределы живут только в «Пределах», ключи хранилища — только в «Данных». Остальные страницы на них ссылаются, а не повторяют.
Что генерируется, а не пишется
| Страница | Источник |
|---|---|
| Справочник достижений | src/achievements/registry.ts |
| Лестница навыков — таблица порогов | src/skills/levels.ts |
| Наборы — состав наборов | src/domain/presets.ts |
| Скриншоты — список кадров | tools/shots/scenarios.mjs |
Загрузчики лежат в docs/.vitepress/data/*.data.mts. Добавили достижение в реестр — справочник обновился сам, править markdown не нужно.
Почему таблицы собраны компонентами, а не markdown
Markdown-таблица с v-for внутри распадается: markdown-it закрывает <table> сразу после строки заголовка, и сгенерированные <tr> оказываются снаружи. Поэтому строки рисуют компоненты (AchGroup, PresetList, ShotList), а заголовки разделов остаются в markdown — ради якорей и правого оглавления.
Шаблон страницы экрана
Восемь заголовков, всегда в этом порядке. Пустые разделы удаляются, а не остаются пустыми.
# Название
> Одна строка: зачем экран нужен.
<главный скриншот>
## Зачем этот экран
## Что на экране — нумерованный список сверху вниз
## Как этим пользоваться — подзаголовки-императивы: «Дописать блок за вчера»
## Пустое состояние
## Пределы и предупреждения
## Чего здесь нельзя — обязательный: гасит половину вопросов
## Рядом — ссылки
::: details Как это работает внутри
только три вещи: файл, инвариант (почему так), ссылка на тест
:::Эталон — «Приоритеты». Новая страница начинается с копирования этой.
Внутри ::: details не пересказывают код. Туда идёт то, чего в коде не видно: почему сделано именно так и что сломается, если сделать иначе.
Порядок работы
Сначала код → потом npm run docs:shots → потом текст.
Обратный порядок даёт снимки, не соответствующие тексту.
| Что изменилось | Что обновить |
|---|---|
Текст на экране (ru.ts) | Страницу экрана и npm run docs:shots |
| Новый экран | Страницу в docs/screens/, пункт сайдбара в config.mts, кадры в scenarios.mjs, запись в SCREEN_PAGES теста |
| Новая шторка | Кадр в манифест и раздел «Как этим пользоваться» |
| Новое достижение, набор или ступень | Ничего — генерируется |
| Лимит (10 приоритетов, 12 навыков, 13 месяцев, 4096 байт) | Только «Пределы» |
| Ключ хранения | Только «Данные» |
| Новый модуль | «Модули», «Настройки» и кадр |
| Правка README | Проверить, что факт не продублирован здесь |
Что проверяется автоматически
tools/docs.test.ts сторожит шесть вещей:
- У каждого
src/screens/*Screen.tsxесть страница вdocs/screens/. Карта имён лежит в самом тесте, поэтому новый экран роняет его на «нет записи в карте», а не проходит молча. Проверка работает и в обратную сторону. - Каждый кадр из манифеста существует как PNG и имеет подпись.
- Каждая ссылка
/shots/…указывает на существующий файл. - Каждый PNG упомянут хотя бы в одной странице — мёртвые кадры не копятся.
- Каждая якорная ссылка ведёт на существующий заголовок.
- В справочнике достижений есть заголовок под каждую группу реестра.
Якоря на кириллице не такие, как кажется
Слагификатор нормализует текст и выкидывает диакритику, поэтому «й» превращается в «и», а «ё» — в «е». Правильная ссылка — #исправить-лишнии-тап, а не #исправить-лишний-тап. Именно поэтому проверка якорей и заведена: на глаз такое не ловится.
Тест лежит в tools/, а не в src/: он ходит по файловой системе, а значит требует типов Node. В src/ это заставило бы добавить "node" в tsconfig приложения, и Node API стали бы видны продуктовому коду, которому их видеть незачем. vite.config.ts включает tools/ в набор тестов специально ради этого.
Плюс npm run docs:build роняется на любой битой внутренней ссылке (ignoreDeadLinks: false), а значит и деплой на Vercel.
Что не проверяется и не будет: соответствие текста поведению кода. Проверить это нельзя, а имитация проверки опаснее её отсутствия.
Тема
Цвета в docs/.vitepress/theme/custom.css скопированы из src/styles/tokens.css вручную. Автоматической связи нет намеренно: документация переживает рефакторинги приложения и не обязана падать вместе с ним. Если токен изменился — поменяйте и здесь.
Рядом
Скриншоты · Строки интерфейса · Архитектура · Сборка и публикация