Соглашения по Markdown

Каноническая справка по форме и форматированию Markdown во всех авторских артефактах .md и .mdx. Сводка в разделе «Conventions» файла CLAUDE.md — это встроенное объявление; эта страница — самостоятельная справка, на которую ссылаются последующие участники.

---

1. ДиалектCopy Anchor Link

Базовым диалектом является GitHub-Flavored Markdown (GFM). Каждый артефакт корректно отображается в веб-интерфейсе GitHub, на сайте документации Fumadocs и в стандартных редакторах с поддержкой Markdown.

2. Иерархия заголовковCopy Anchor Link

Один H1 на файл. Последующие заголовки спускаются монотонно (H2 → H3 → H4), не пропуская уровней. В заголовках с заглавной буквы пишется только первое слово; никаких ЗАГЛАВНЫХ БУКВ ЦЕЛИКОМ, никаких Заглавных Букв В Каждом Слове. H1 несёт основной заголовок документа. На странице сайта документации поле title во фронтматтере отображается как H1 и служит якорем страницы в навигации сайта документации, поэтому тело страницы начинается с H2.

3. Блоки кодаCopy Anchor Link

Огороженные блоки кода объявляют свой язык (```python, ```bash, ```yaml, ```json, ```mermaid). Блоки без тега отключают подсветку синтаксиса и сигнализируют о дрейфе авторской практики; правило markdownlint MD040, настроенное в .markdownlint.json, требует наличия тега языка.

4. Внутренние ссылкиCopy Anchor Link

Внутренние перекрёстные ссылки используют пути от корня сайта (например, [Authorship header](/docs/reference/authorship-header)). Голые пути относительно репозитория с расширением .md/.mdx (/docs/foo.md) и полные URL того же репозитория (https://github.com/ahmed-g-gad/apothem/blob/main/...) не используются для ссылок внутри сайта, потому что они плохо переносят переименования страниц и реорганизацию разделов.

Валидатор link-check разрешает эти пути от корня сайта /docs/... — а также форму /<locale>/docs/... для локалей группы, отличных от локали по умолчанию, — относительно набора страниц на диске в site/content/docs/: /docs/a/b соответствует site/content/docs/a/b.mdx или индексу папки site/content/docs/a/b/index.mdx, а форма с локалью соответствует пути в поддереве site/content/docs/<locale>/. Ссылка на удалённый или переименованный маршрут не разрешается ни в один из этих файлов, и link-check, рекомендательный сопоставитель, не проваливающий запуск (см. §6), сообщает о ней как о мёртвом маршруте (видимая пользователю ошибка 404).

Внешние ссылки на изменяемые ref (main, master, latest, HEAD) закрепляются по SHA коммитов или по тегам релизов всякий раз, когда важна стабильность содержимого по ссылке; нестабильные ссылки документируются как таковые соседним комментарием {/* volatile */}.

5. Заголовок авторстваCopy Anchor Link

Каждый артефакт Markdown (за исключениями, перечисленными в src/apothem/schemas/header-exceptions.txt) несёт канонический заголовок авторства — единственную строку SPDX-License-Identifier: MIT — в варианте комментария, соответствующем типу его файла, согласно странице Заголовок авторства: комментарий HTML в файлах .md и комментарий {/* ... */} в файлах .mdx. Без фронтматтера строка заголовка — это строка 1. При наличии YAML-фронтматтера фронтматтер остаётся на байте 0, а строка заголовка следует за закрывающей ---.

6. ВалидаторыCopy Anchor Link

Хук pre-commit markdownlint в .pre-commit-config.yaml запускает markdownlint-cli с политикой правил из .markdownlint.json и обеспечивает соблюдение большей части правил из §§1–4. Рабочий процесс Markdown Lint запускает тот же хук в CI при каждом push в main и при каждом pull request, затрагивающем файлы Markdown, поэтому CI выполняет проверку той версией, которую закрепляет хук. Политика отключает MD013 (длина строки), MD033 (встроенный HTML) и MD041 (заголовок в первой строке). Она также отключает MD038, потому что канонический постфикс метки опции (Recommended) сохраняет ведущий пробел внутри фрагмента кода, и MD060, потому что ни один стиль столбцов таблицы не принимает таблицы с компактными ячейками и плотной строкой-разделителем |---|, которые использует корпус. MD024 проверяет только заголовки с общим родителем, поэтому заголовки Added, Changed, Fixed и Security, которые повторяются в CHANGELOG.md в каждом релизе, проходят проверку. Причины каждого решения изложены рядом с хуком. Хук пропускает деревья тестовых фикстур tests/fixtures/, tests/conformity/, tests/conformity-scenarios/fixtures/ и tests/scripts/inject-header/fixtures/, байты которых задают тесты. Он также пропускает plugins/claude-code/, который python scripts/dev/assemble_plugin_tree.py генерирует из src/apothem/: каждый нумерованный шаг команды становится отдельным файлом, так что список в файле шага начинается с номера этого шага. Исходные файлы в src/apothem/ проверяются, поэтому найденную в содержимом плагина проблему исправляют там, а затем регенерируют дерево плагина.

file-header-grep в src/apothem/conformity/file_header_grep.py проверяет §5. Валидатор link-check в src/apothem/conformity/link_check.py проверяет дисциплину разрешения ссылок из §4: он разрешает относительные ссылки относительно каталога исходного файла, а маршруты сайта /docs/... (и /<locale>/docs/...) — относительно набора страниц site/content/docs/, помечая любые, которые не разрешаются ни в одну страницу на диске. Оба являются рекомендательными сопоставителями, срабатывающими при каждой операции Write. Они выполняются в хуке pre-commit conformity-corpus-perwrite и в задании corpus-perwrite-gate рабочего процесса Conformity в .github/workflows/conformity.yml, и в обоих местах сообщают о находках, не проваливая запуск. Команда python -m apothem.conformity.gate --all . --strict в задании quality CI в .github/workflows/ci.yml охватывает только автономные валидаторы, поэтому не запускает ни один из них.