# Md Doc > Markdown-документ с вёрсткой как в Word + обязательная HTML-версия: отчёты, справки, ТЗ, письма оператору. Триггеры: «напиши отчёт/справку», «оформи в md», «версия для печати». Молчаливо — когда связный текст длиннее экрана уходит оператору или в репо. Научный регистр → rn-article-style; хендофф → сначала session-handoff за структурой, здесь лишь вёрстка поверх. - Skill: `vibeengineering-llc/md-doc` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add vibeengineering-llc/md-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/vibeengineering-llc/md-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: VibeEngineering-LLC (https://skillmd.com/u/vibeengineering-llc) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vibeengineering-llc/md-doc --- # 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` делает эту вторую версию, не трогая исходник: ```bash 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 ```bash 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.