# Стиль документации на GitHub

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

## Что рендерит GitHub, а что нет

| Конструкция | Поддержка | Замечание |
|---|---|---|
| Заголовки `#` … `######` | да | один `H1` на документ; уровни не пропускаются |
| Таблицы с `\|` | да | число ячеек в строке обязано совпадать с заголовком |
| Экранированная черта `\|` в ячейке | да | без экранирования ячейка разрежется |
| Inline-код с чертой: `` `a \| b` `` | да | внутри кода спасает обратная кавычка |
| Блок кода с языком | да | без языка подсветки нет, а линтер предупреждает |
| `> [!NOTE]` … `> [!CAUTION]` | да, ровно пять типов | `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION` (документация GitHub) |
| Сноски `[^1]` | да | рендерятся внизу независимо от места объявления |
| Задачи `- [ ]` | да | в README и issue |
| `<details><summary>` | да | свёрнутый блок для длинных логов |
| Математика `$…$`, `$$…$$` | да | в вики тоже |
| Mermaid | да | ` ```mermaid `; в вики поддерживается |
| Относительная картинка в вики | **нет** | вики — отдельный репозиторий, дерево проекта не видно |
| Автоматическое оглавление в тексте | **нет** | у читателя есть панель Outline, но в файл оглавление не вставляется |
| Вложенные страницы в вики | **нет** | плоское пространство файлов |

## Якоря заголовков

Правила GitHub (документация «Basic writing and formatting syntax»):

1. Регистр приводится к нижнему.
2. Пробелы становятся дефисами.
3. Прочие пробельные символы и знаки препинания удаляются.
4. Пробелы по краям удаляются.
5. Разметка удаляется, остаётся текст: `_курсив_` → `курсив`.
6. Повтор заголовка в документе получает суффикс `-1`, `-2`.

Следствия, которые чаще всего ломают ссылки:

- `## Помочь проекту — фактами, а не активностью` → `#помочь-проекту--фактами-а-не-активностью`:
  тире удаляется, два соседних пробела дают **два** дефиса;
- кириллица сохраняется: `#установка`, а не транслитерация;
- `## API и MCP` → `#api-и-mcp`.

Замер и оговорка: документация GitHub в одном примере показывает якорь с заглавной
греческой буквой (`…#letter-Θ`), что противоречит правилу о нижнем регистре. Поэтому
`ghagent` сравнивает якоря без учёта регистра — иначе он давал бы ложный `FAIL` на
документе самой платформы.

## Тон и содержание

- Пишите то, что читатель может проверить: команду, файл, число, ответ API.
- Никаких оценок без единицы измерения: «быстро» не заменяет «0,4 с на 10 000 строк».
- Числа в таблице «В цифрах» сопровождаются источником: командой или путём.
- Одна мысль — одно предложение. Абзац до пяти строк.
- Эмодзи в метаданных, заголовках и описании репозитория не используются: их читают
  поиск и парсеры.
- Превосходные степени («blazing fast», «лучший») не используются: они не проверяемы и
  снижают доверие.

## Раскладка README

1. `H1` — название до 60 символов.
2. Абзац: что это, для кого, чем отличается.
3. Бейджи: CI, релиз, лицензия, среда. 3–8 штук, не больше.
4. Оглавление от `H2`, если документ длиннее 200 строк.
5. Установка → быстрый старт → настройка → возможности → ограничения → документация →
   разработка → участие → лицензия. Порядок можно менять, набор — нет.

## Раскладка страницы вики

1. `H1` — название страницы (файл без `.md`).
2. Один абзац: зачем эта страница.
3. Содержание от `H2`, если страниц больше пяти.
4. Ссылки на соседние страницы — без `.md`.
5. В конце — ссылка на репозиторий или соседнюю страницу: читатель не должен упираться
   в тупик.

## Ошибки, которые пакет считает блокирующими

| Дефект | Правило |
|---|---|
| BOM, CRLF, отсутствие перевода строки в конце | `doc.bom`, `doc.crlf`, `doc.final-newline` |
| Второй `H1`, пропущенный уровень | `md.h1`, `md.heading-skip` |
| Незакрытый блок кода | `md.fence` |
| Строка таблицы с другим числом ячеек | `md.table` |
| Ссылка на несуществующий файл или якорь | `md.link-local`, `md.link-anchor` |
| Оглавление, ведущее на несуществующий заголовок | `md.toc` |
| Токен, приватный ключ, абсолютный путь машины | `privacy.secret`, `privacy.abs-path` |