Перейти к основному содержимому

Правила оформления документов

Версия: 1.0 Дата: 25.04.2026 Статус: Готов к обсуждению

Единые правила оформления MD-документов в системе документации. Действуют для всех проектов. Создавался на основе реального опыта работы с Docusaurus + Decap CMS + DocMap MCP, после ряда инцидентов, где неверное оформление ломало сборку, индексацию или CMS-редактор.

Принцип​

Каждый создаваемый или правленый документ должен работать с первого раза:

  • собираться Docusaurus (npm run build без ошибок MDX);
  • открываться в Decap CMS (/admin/index.html) для редактирования;
  • индексироваться DocMap MCP (docs_search находит его);
  • читаться человеком как связный русский текст.

Это достигается соблюдением чек-листа при создании и правке.

1. Frontmatter — обязательный шаблон​

В начале каждого MD-документа:

---
title: "Название документа на русском (английский термин в скобках при необходимости)"
draft: false
---

Обязательные требования:

  • title: в двойных кавычках. Кавычки нужны, если в названии есть двоеточие, дефис рядом с кириллицей, кавычки внутри. Безопаснее — всегда в кавычках.
  • draft: false обязателен. Без него документ не виден в production build (npm run build) и в публичном экспорте. Decap CMS schema требует это поле.
  • Парные разделители --- сверху и снизу frontmatter.
  • Кодировка UTF-8 без BOM.
  • Никаких legacy-полей: sidebar_position, sidebar_label, id, slug — кроме редких случаев, когда документ требует особого порядка в сайдбаре с явным обоснованием.

Черновики (видны только в dev-сервере, не в production):

---
title: "Черновик"
draft: true
---

2. Шапка документа — обязательная после H1​

После заголовка H1, через пустую строку — шапка с метаданными:

# Название документа на русском

**Версия:** 1.0
**Дата:** ДД.ММ.ГГГГ
**Статус:** Готов к обсуждению

Обязательные требования:

  • H1 идентичен title: во frontmatter (без кавычек).
  • Между H1 и **Версия:** обязательная пустая строка. Без неё Decap CMS body parser не отделяет шапку от заголовка, и редактирование в CMS-админке выдаёт визуальные артефакты.
  • **Версия:** повышается при существенных изменениях документа.
  • **Дата:** обновляется при каждом существенном изменении (формат ДД.ММ.ГГГГ).
  • **Статус:** — один из:
    • Черновик — документ в работе, концепция не зафиксирована.
    • Готов к обсуждению — концепция оформлена, ждёт ревью или утверждения.
    • Утверждён — концепция принята, изменения только через явное согласование.
    • Черновик (архивная версия) — документ переведён в архив, актуальная версия в другом файле.

Исключения (шапка не нужна):

  • index.md проекта — генерируется скриптом tools/build_project_index.sh.
  • _category_.json — JSON-конфиг, не MD-документ.
  • Навигационные index.md отдельных разделов — если есть.

3. Язык​

3.1. Только русский в основном тексте​

Все новые и обновляемые документы пишутся только на русском языке в человеко-читаемом формате оборотов речи.

3.2. Запрет смешения языков в одном предложении​

Нельзя:

«platform должна различать quoted promise и settlement-relevant figures».

Нужно:

«Платформа должна различать зафиксированное коммерческое обещание (quoted promise) и величины, значимые для взаиморасчётов (settlement-relevant figures)».

3.3. Английские термины — обязательно с расшифровкой в скобках​

При первом упоминании в документе и в каждом ключевом контексте — обязательная пара «русское пояснение (английский термин)»:

  • «поверхность взаимодействия (surface)»;
  • «коммерческая фиксация (quote, quoted promise)»;
  • «повторная проверка (revalidation) и пересчёт цены (repricing)»;
  • «взаиморасчёт с поставщиком (supplier settlement)»;
  • «тенантная изоляция (tenant isolation)»;
  • «учёт потребления (metering) и квоты (quotas)».

При повторном упоминании в одном документе допустимо использовать только русское пояснение или только английский термин — но не смешанный оборот.

3.4. Названия документов и заголовки — на русском​

Заголовки H1–H6, названия разделов, label в _project_.json и _category_.json — на русском. Английский — в скобках как пояснение.

Примеры:

  • ❌ # Tour Builder Domain — Композиция, черновики и публикации
  • ✅ # Домен сборки тура (Tour Builder) — композиция, черновики и публикации

3.5. Имена сущностей в коде — на английском​

Имена сущностей в JSON, YAML, кода — оставляются на английском (как в реальной системе): Property, Offer, Quote, Booking, pending_supplier_confirmation. В русском тексте — обязательное пояснение: «коммерческая фиксация (Quote)», «состояние ожидания подтверждения поставщика (pending_supplier_confirmation)».

3.6. Исключения​

  • Цитаты внешних источников (контракты поставщиков на английском) — оригинал + перевод.
  • Нормативы (GDPR, EU TOMS, Package Travel Directive 2015/2302, PSD2 SCA) — официальное английское название + русская расшифровка.
  • Имена технологий и протоколов (PostgreSQL, Redis, Kubernetes, OpenAPI, AsyncAPI, gRPC, JSON, MDX) — без перевода.

4. MDX-безопасное написание​

DocMap-индексируемые документы рендерятся Docusaurus с MDX-парсером. MDX трактует любой < за которым идёт цифра или буква как начало JSX-тега. Это ломает сборку.

Опасные конструкции:

  • ❌ <2s, <500ms, <1.5s, <15 min — парсер ищет JSX-тег <2s>.
  • ❌ >2 сервиса — обычно работает, но небезопасно.
  • ❌ <TagName> — если не намеренный JSX, парсится как открытие компонента.

Безопасные формы:

  • ✅ &lt;2s, &lt;500ms — HTML-entity, визуально идентично, парсер не путает.
  • ✅ < 2s — с пробелом, если стилистически уместен.
  • ✅ `<2s` — внутри backtick-кода MDX не парсит JSX.
  • ✅ Внутри ``` ``` (fenced code block) — всё безопасно.

Обязательная проверка после записи документа:

grep -nE '<[0-9]' путь/к/файлу.md   # должно быть пусто
grep -nE '>[0-9]' путь/к/файлу.md   # обычно пусто

При совпадениях — массовая замена:

sed -i 's/<\([0-9]\)/\&lt;\1/g' путь/к/файлу.md

Подробности и причины — в MDX-безопасное написание.

5. Имена файлов​

  • Имя файла на русском с пробелами допустимо: Правила оформления документов.md, Деплой на VPS — Docker + Traefik.md. Это договорённость существующих документов cms-system.
  • Расширение .md обязательно.
  • Без точек в имени кроме расширения.
  • Архивные документы — суффикс -old-YYYY-MM-DD: Имя документа-old-2026-04-25.md.

В технических slug-папках (docs/<project-slug>/, assets/, <section>/) — только латиница строчная, цифры, дефис: vitiana-api-platform, compliance-and-legal. Пробелы и кириллица в slug запрещены.

6. Размещение документа​

Документ кладётся в один из четырёх стандартных разделов проекта:

  • overview/ — зачем существует проект, контекст, архитектура, ключевые решения, манифест.
  • reference/ — точные спецификации, схемы, контракты, конфиги, доменные модели.
  • operations/ — как запускать, деплоить, обслуживать, чинить, runbook, SLA, DR.
  • development/ — роадмап, ADR, планы, история изменений, ТЗ подрядчику, governance.

В корне проекта (docs/<slug>/) лежат только _project_.json, index.md (генерируемый), assets/ (медиа). Документы в корне проекта запрещены.

В корне docs/ лежат только папки проектов. Документы в корне docs/ запрещены.

7. Связанная документация — обязательная секция в конце​

В конце каждого документа — секция ## Связанная документация с явными markdown-ссылками на верхнеуровневые документы и соседние reference-документы:

## Связанная документация

- [Закон 00000 — платформа главенствует над поставщиками](../development/Закон%2000000%20—%20платформа%20главенствует%20над%20поставщиками.md) — высший приоритет.
- [MDX-безопасное написание](MDX-безопасное%20написание.md) — техника безопасности при правке.

Никаких «висящих» утверждений без обоснования и ссылки.

8. Картинки и медиафайлы​

Источник правды — папка assets/ внутри папки проекта:

docs/
  vitiana-api-platform/
    assets/
      architecture.jpg

Скрипт tools/sync_assets.sh синхронизирует assets/ → static/<slug>/ перед каждой сборкой. Папка static/<slug>/ — производная, не редактировать вручную.

Синтаксис вставки в MD-документ:

![Описание](/vitiana-api-platform/architecture.jpg)

Путь начинается с / — абсолютный от корня сайта. Тег <img> не использовать — создаёт проблемы компиляции MDX.

Запрещено:

  • Картинки в static/ напрямую — синхронизация затрёт.
  • Картинки в docs/_uploads/ (временная папка для CMS-загрузок, в .gitignore).

9. Создание нового документа — порядок​

  1. Определить раздел: overview/ / reference/ / operations/ / development/.
  2. docs_search(тема, project="<slug>") — найти соседние документы для контекста.
  3. docs_get_section — прочитать релевантные секции соседей.
  4. Спроектировать структуру нового документа (заголовки H2/H3).
  5. docs_create_file со стандартным frontmatter и шапкой.
  6. Развернуть содержание секциями.
  7. Секция ## Связанная документация в конце.
  8. После записи: grep -nE '<[0-9]' для MDX-safe.
  9. После записи: docs_search(ключевое_слово) — документ должен появиться в результатах (DocMap watcher переиндексировал).
  10. Если новый файл изменил структуру разделов — tools/build_project_index.sh <slug> для перегенерации index.md проекта.

10. Правка существующего документа — порядок​

  1. docs_get_section — прочитать текущее содержимое нужной секции.
  2. docs_links(section_id, direction="both") — получить forward-links и backlinks.
  3. Прочитать соседние документы из backlinks (контекст связанных логик).
  4. Обновить только нужное через docs_patch_section (тело секции, заголовок не меняется).
  5. Поднять **Версия:** и **Дата:** в шапке при существенных изменениях.
  6. После записи: grep -nE '<[0-9]' для MDX-safe на новом теле.
  7. После записи: docs_links для проверки целостности обратных ссылок.

11. Архивация документа​

Если документ заменяется новой версией — переводить в архив, не удалять содержимое:

  1. docs_rename_file <file>.md → <file>-old-YYYY-MM-DD.md.
  2. docs_patch_section шапки — поменять frontmatter и шапку:
---
title: "Оригинальное название (архивная версия 2.0)"
draft: false
---
# Оригинальное название (архивная версия 2.0)

**Версия:** 2.0 (архивная)
**Дата:** [исходная дата] (создание), ДД.ММ.ГГГГ (архивация)
**Статус:** Черновик (архивная версия)

> ⚠ **Этот документ переведён в архивный режим [дата].** Актуальная версия — [Имя нового документа](Имя%20нового%20документа.md). Документ сохранён как историческая запись.

Никогда не удалять содержимое архивного документа.

Подробности — в Архивация документов — никогда не удалять.

12. Запрещённые паттерны​

  • ❌ Запись документа без draft: false во frontmatter.
  • ❌ Запись документа без пустой строки между H1 и шапкой.
  • ❌ Запись документа без MDX-safe проверки.
  • ❌ Документ в корне проекта или в корне docs/ (только в overview/ reference/ operations/ development/).
  • ❌ Картинки в static/ напрямую.
  • ❌ index.md проекта вручную (только через tools/build_project_index.sh).
  • ❌ _project_.json access[] вручную (только через tools/add_user.sh).
  • ❌ static/admin/index.html CREDENTIALS_HASH вручную (только через tools/add_user.sh --admin).
  • ❌ docusaurus.config.ts url/title вручную (только через cms-config.json).
  • ❌ Удаление содержимого архивного документа (только rename + статус Черновик).
  • ❌ Смешение русского и английского в одном предложении.
  • ❌ Английский термин без русской расшифровки при первом упоминании.

Связанная документация​