Форматтер Markdown

Что исправляет форматтер

• Маркеры списков. *, -, + нормализуются к одному единому символу (по умолчанию -).
• Иерархия заголовков. Предупреждает (или повышает уровень), когда за H2 следует H4 без H3 между ними.
• Пустые строки. Ровно одна пустая строка между блоками; никаких серий из трех и более.
• Таблицы. Дополняет каждый столбец так, чтобы вертикальные черты выравнивались в исходнике, хотя рендерерам Markdown это безразлично.
• Конечные пробелы. Убирает пробелы в конце каждой строки, кроме намеренного маркера переноса из двух пробелов.
• Ссылочные ссылки. Собирает определения [label]: url в конце документа, отсортированные по алфавиту.
• Ограждения кода. Тег языка нормализуется к нижнему регистру; блоки кода на основе отступов становятся огражденными блоками.

Параметры стиля, которые можно задать

Почему важен единообразный Markdown

В командном репозитории неединообразный Markdown порождает шумные диффы: каждый раз, когда кто-то сохраняет файл в другом редакторе, маркеры списков меняются, а таблицы переформатируются. Форматтер обеспечивает единый стиль, поэтому ревьюеры pull request видят только изменения содержимого. Считайте это prettier для прозы.

Когда не форматировать

• Огражденные блоки кода остаются байт в байт нетронутыми, форматтер никогда не трогает содержимое блока кода. Если форматирование меняет код, это баг.
• Намеренные жесткие переносы на узкой ширине (readme.md в терминальном проекте) перепереносятся, если вы включите колонку переноса. Отключите перенос, если храните вручную настроенные переносы строк.
• Встроенные блоки HTML проходят без изменений.

Замены drop-in

Если вы предпочитаете локальный CLI, форматтер использует те же правила AST, что и remark-stringify с плагином remark-gfm. prettier --parser markdown дает похожий результат.