md-doclisted

# 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).