md-doc — документ в Markdown с вёрсткой документа

Markdown — исходник, HTML — читаемый вид. Оба обязательны: .md правится и версионируется, .html открывается двойным кликом и печатается в PDF без вёрстки заново.

Скрипт: scripts/md2html.py (Python 3, пакет markdown; на этой машине установлен).

1. Как писать сам Markdown

Абзац — одна строка. Никаких жёстких переносов по ширине окна. Перенос внутри абзаца ломает git diff (правка одного слова красит четыре строки), ломает автоматическую расстановку переносов в HTML и мешает поиску по фразе. Пустая строка между абзацами — единственный разделитель.

Один H1 на документ, дальше H2 и H3. Через уровень не прыгать: H1 → H3 читается как пропущенный раздел. Глубже H4 не уходить — если понадобилось, документ пора делить.

Таблица вместо перечисления параметров. Три и более однотипных пункта с двумя и более признаками — это таблица, а не список. Шапка обязательна, выравнивание колонок не задавать без нужды.

Списки: маркированный — когда порядок не важен; нумерованный — когда важен (последовательность действий, приоритет, порядок закрытия). Смешивать в одном перечне нельзя.

Код и пути — в обратных кавычках. Многострочное — в огороженный блок с указанием языка (```python, ```bash). Вывод команды и саму команду в один блок не сваливать.

Цитата первоисточника — блочная цитата >, дословно, с адресом. Пересказ цитатой не оформлять — это разные вещи ([[sci-search]] §1, citation-green).

Полные пути от диска или объявленного корня, без относительных ссылок.

2. Русская типографика

Единицы — СИ. Скрипт с ключом --nbsp сам ставит неразрывные пробелы между числом и единицей, в стр. 38, рис. 3, § 12, и превращает " в ёлочки, -- в тире. Внутри кодовых блоков не трогает ничего.

3. Форматирование самого .md

Абзац одной строкой — правило git diff. Оператору для чтения .md глазами нужен второй вид: строки одинаковой ширины и ровный правый край, как в документе. Скрипт scripts/mdfmt.py делает эту вторую версию, не трогая исходник:

python ~/.claude/skills/md-doc/scripts/mdfmt.py ОТЧЁТ.md --width 90

Пишет на место, .bak рядом. Ключи: --width N (умолчание 90), --ragged — без выключки (ровный только левый край), --out ПУТЬ, --stdout. Огороженные блоки кода, таблицы, YAML-шапка и HTML не рвутся; inline-код в обратных кавычках не разрывается по пробелу.

Правило контура: репозиторный .md — с абзацем в одну строку (это исходник для диффа). HTML-версия md2html.py собирается из ЛЮБОГО из двух — переносы внутри абзаца в вёрстке игнорируются.

⚠ mdfmt.py — только для чтения в «голом» текстовом редакторе (Notepad, cat, less). НЕ прогонять .md, который оператор откроет в РЕНДЕРЕ (окно Claude Code, GitHub, preview в VS Code): рендер показывает жёсткие переносы как переносы строк, а выключку — как рваные двойные пробелы. Замечание оператора 12.09.2026 дословно: «почему такие странные переносы?» — причина была именно в этом. Для рендера абзац всегда одной строкой; красивый постраничный вид даёт HTML.

4. Сборка HTML

python ~/.claude/skills/md-doc/scripts/md2html.py ОТЧЁТ.md --nbsp

Выход — ОТЧЁТ.html рядом с исходником. Заголовок вкладки берётся из первого H1.

СТАНДАРТ — А4 (оператор, 12.09.2026: «вёрстка под А4 — это вообще стандарт должен быть»). Пресет a4 — умолчание: полоса набора соответствует странице 210 × 297 мм при полях 20 × 18 мм, @page { size: A4 portrait }, на экране лист с тенью на сером поле — то, что видно в браузере, совпадает с тем, что выйдет на печать и в PDF. Ключ --preset указывать не нужно; doc и article остаются для случаев, когда широкие таблицы в А4 не помещаются, и это осознанный выбор.

Несколько файлов за раз: перечислить через пробел.

Вёрстка: заголовки с синей линейкой, таблицы с шапкой и чередованием строк, цитаты с жёлтой полосой, выключка по формату с переносами, широкие таблицы прокручиваются горизонтально. Печать: поля 20 × 18 мм, заголовки не отрываются от текста, таблицы и блоки кода не разрываются между страницами.

5. Проверка перед выдачей

[ ] Абзацы одной строкой, жёстких переносов нет
[ ] Один H1, уровни не пропущены
[ ] Однотипные перечисления сведены в таблицы
[ ] Десятичная запятая, ёлочки, длинное тире
[ ] Числа не отрываются от единиц (--nbsp)
[ ] Пути полные
[ ] HTML собран и открывается
[ ] Длинные таблицы читаемы, код не уезжает за край
[ ] Отчёт оператору: `report_lint.py` вернул 0 (§ 6)

6. Отчёт оператору — отдельный жанр со своими рубежами

Отчёт читают глазами и печатают на A4, поэтому к нему правила жёстче, чем к репозиторному документу. Проверяются они программой, а не на глаз:

python ~/.claude/skills/md-doc/scripts/report_lint.py ОТЧЁТ.md

Программа печатает нарушения строками файл:строка: КОД: пояснение и возвращает код 1, пока остаётся хоть одна ошибка. Отчёт с ненулевым кодом возврата оператору не уходит. Предупреждения кода возврата не меняют. Проверять код возврата только напрямую: $? после конвейера с tail показывает код tail, а не программы (поймано на приёмке).

Тесты — scripts/test_report_lint.py (13 проверок, из них одна с 20 мутационными подслучаями): python test_report_lint.py. Правило, добавленное без своего мутационного подслучая, считается непринятым.

Ширина — 90 символов. Абзац в одну строку остаётся правилом для репозитория, но отчёт перед выдачей прогоняется через mdfmt.py --width 90. Строка на 700–1200 символов, которую редактор сворачивает в экран шириной с монитор, читается как сплошная простыня и на печати рвётся произвольно.

Таблица — не более четырёх колонок, 110 символов в строке, 120 символов в ячейке. Ячейка на треть страницы — это не таблица, а абзац, загнанный в клетку: колонки разъезжаются, на A4 таблица уходит за поле. Не помещается — значит, это текст или список определений.

Абзац — не длиннее 900 символов, это примерно шесть предложений. Длиннее — делить по мысли, а не по длине.

Источник называется именем, а не адресом. В тексте — «Радиационная гигиена» (Ильин, Кириллов), с. 38 — так читатель понимает, на что он смотрит, без перехода по ссылке. Адреса в интернете собираются в раздел «Источники» в конце документа и приводятся полностью. Пути к локальным файлам в отчёт НЕ выкладываются никогда — ни в текст, ни в «Источники» (оператор, 12.09.2026: «просто список книг. Пути никогда не выкладывай в таких доках»). Книга из библиотеки — библиографическое описание, и только оно. Пути к файлам сообщаются оператору в чате (§18), а не в документе. Туда же — пути к скриптам расчёта. Адрес посреди фразы и ссылка с подписью «здесь» — нарушение.

Язык — русский. Замены берутся из двух словарей JSON Lines: references/style-replacements.jsonl (поля bad, good, domain, status, note, source, added; status: canon даёт ОШИБКУ, candidate — предупреждение) и <home>\.claude\skills\terminology\data\terms.jsonl (запрещённые варианты — поле synonyms_bad, правильный — поле term; ЧУЖАЯ ЗОНА, только чтение). Отсутствие любого из них отключает правило, но программу не роняет — об этом говорит строка в разделе «Примечания» вывода. Иной путь к словарю — ключ --dict ПУТЬ, его можно повторять. Сейчас все 47 записей словаря стиля — кандидаты (решение оператора 12.09): канон присваивает ведущий словаря, а не автор заявки, поэтому правило Я-1 по словарю стиля пока даёт только предупреждения. Ошибку по-прежнему дают записи словаря терминов, у которых канон проверен. Словари намеренно узкие: в них только то, чему есть точная замена. Термины, у которых её нет (спектр, изотоп, калибровка, репозиторий), не трогаются — иначе правило превращается в шум и его перестают выполнять. Встретилось новое слово — дописать строку в словарь в тот же ход.

Структура. H1 — предмет отчёта и дата. Дальше: краткий ответ (не длиннее десяти строк, чтобы читатель получил суть сразу), обоснование, что и как проверено, ограничения (чего проверка не покрывает), «Источники». Раздел ограничений обязателен: отчёт без него читается как утверждение о полноте, которой не было.

Анти-паттерны

Связанные скиллы

• rn-article-style — научный регистр, структура статьи, ГОСТ/ВАК. Для публичных текстов сначала он, этот скилл — вёрстка поверх.
• sci-search — разметка уровня проверки ✅/📗/⚠️ в документах с внешними фактами.
• markitdown — обратное направление: готовый документ (PDF, docx, xlsx) → Markdown.