VibeEngineering-LLC 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. Русская типографика
| Что | Правильно | Неправильно |
|---|---|---|
| Десятичный разделитель | 7,5 % | 7.5 % |
| Кавычки | «ёлочки», внутри „лапки“ | "программистские" |
| Тире в тексте | — (длинное), с пробелами | - или -- |
| Дефис | научно-технический | – |
| Число и единица | 662 кэВ (неразрывный пробел) | разрыв строки между ними |
| Диапазон | 0,304…1,000 или 5–7 % | 5 - 7 % |
| Знак процента | 7,5 % (с пробелом) | 7,5% |
Единицы — СИ. Скрипт с ключом --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 — с абзацем в одну строку (это исходник для
диффа); отчёт оператору .md — прогнать mdfmt.py --width 90. HTML-версия
md2html.py собирается из ЛЮБОГО из двух — переносы внутри абзаца в вёрстке
игнорируются.
4. Сборка HTML
python ~/.claude/skills/md-doc/scripts/md2html.py ОТЧЁТ.md --nbsp
Выход — ОТЧЁТ.html рядом с исходником. Заголовок вкладки берётся из первого H1.
| Ключ | Зачем |
|---|---|
--preset doc |
внутренний документ, отчёт, конспект (умолчание): колонка 1150 px, кегль 15 px |
--preset article |
публикуемый текст, читается подряд: колонка 960 px, кегль 17 px |
--nbsp |
неразрывные пробелы и типографика (включать почти всегда) |
--toc |
оглавление в начале — для документов длиннее пяти разделов |
--title "…" |
заголовок вкладки, если он не совпадает с H1 |
--out ПУТЬ |
иное имя выхода (только при одном входном файле) |
--stdout |
печать в поток вместо файла |
Несколько файлов за раз: перечислить через пробел.
Вёрстка: заголовки с синей линейкой, таблицы с шапкой и чередованием строк, цитаты с жёлтой полосой, выключка по формату с переносами, широкие таблицы прокручиваются горизонтально. Печать: поля 20 × 18 мм, заголовки не отрываются от текста, таблицы и блоки кода не разрываются между страницами.
5. Проверка перед выдачей
[ ] Абзацы одной строкой, жёстких переносов нет
[ ] Один H1, уровни не пропущены
[ ] Однотипные перечисления сведены в таблицы
[ ] Десятичная запятая, ёлочки, длинное тире
[ ] Числа не отрываются от единиц (--nbsp)
[ ] Пути полные
[ ] HTML собран и открывается
[ ] Длинные таблицы читаемы, код не уезжает за край
Анти-паттерны
| Избегать | Почему |
|---|---|
| Жёсткий перенос строк в абзаце | ломает diff, поиск и вёрстку |
Выдать только .md оператору |
читать сырой markdown с экрана неудобно, это и была причина правила |
Заголовки жирным текстом вместо ## |
не попадают в оглавление и в структуру |
| Таблица шире семи колонок | не читается ни на экране, ни на печати; делить или транспонировать |
| Вложенность списков глубже двух уровней | признак, что нужен подраздел |
| Скриншот таблицы вместо таблицы | не ищется, не копируется, не печатается |
| Точка в конце заголовка | типографическая ошибка |
Связанные скиллы
rn-article-style— научный регистр, структура статьи, ГОСТ/ВАК. Для публичных текстов сначала он, этот скилл — вёрстка поверх.sci-search— разметка уровня проверки ✅/📗/⚠️ в документах с внешними фактами.markitdown— обратное направление: готовый документ (PDF, docx, xlsx) → Markdown.