Освоение списков Markdown: стандарты отступов CommonMark и GitHub Flavored Markdown (GFM)
Техническая основа рендеринга списков Markdown
Markdown зарекомендовал себя как стандартный язык разметки для современной технической документации, спецификаций программного обеспечения, личных баз знаний и общения разработчиков. Хотя одноуровневые маркированные списки (- элемент) и нумерованные списки (1. элемент) выглядят простыми, создание глубоко вложенных многоуровневых структур документов влечет за собой высокую сложность форматирования. Различные парсеры Markdown, такие как CommonMark, GitHub Flavored Markdown (GFM), Python-Markdown и Pandoc, применяют строгие и тонкие правила касательно выбора маркеров списков, соотношения табуляций и пробелов, а также отступов подблоков.
Когда списки вставляются из разных текстовых редакторов (таких как VS Code, Sublime Text, Xcode, Заметки Apple или Microsoft Word), возникают невидимые ошибки отступов. Один пропущенный пробел у вложенного элемента приводит к тому, что компилятор Markdown интерпретирует дочерний узел как верхнеуровневый элемент или отдельный абзац. Форматировщик вложенных списков и отступов Utiliome устраняет эти аномалии парсинга, анализируя AST (абстрактное синтаксическое дерево) вашего входного текста и повторно генерируя стандартизированный Markdown, полностью соответствующий спецификациям.
Правила отступов: 2 пробела против 4 пробелов
Один из самых частых споров в проектировании технической документации — использование 2 или 4 пробелов на один уровень иерархии. Выбор зависит от спецификации целевого парсера Markdown:
Правило 2 пробелов (Стандарт GFM и Prettier): В современных экосистемах веб-документации, таких как GitHub, Docusaurus, Nextra и Obsidian, стандартом является 2 пробела на уровень отступа. Это выравнивает дочерний контент ровно под началом текста родительского элемента:
- Элемент верхнего уровня 1 - Вложенный дочерний элемент 1.1 - Вложенный дочерний элемент 1.2 - Глубоко вложенный элемент 1.2.1 - Элемент верхнего уровня 2Правило 4 пробелов (Строгий CommonMark и Python-Markdown): Строгие реализации CommonMark требуют, чтобы дочерние блоки, фрагменты кода и вложенные списки внутри нумерованных списков имела отступ в 4 пробела (или 1 табуляцию) для гарантированного сохранения структуры родительского блока:
1. Первый шаг в рабочем процессе - Связанный подпункт A - Связанный подпункт B 2. Второй шаг в рабочем процессеЛовушки смешивания табуляций и пробелов: Смешивание символов табуляции (
\t) и пробелов ASCII (\x20) — главная причина сбоев отображения документации Markdown. Веб-движки интерпретируют табуляцию по-разному (часто как 4 или 8 колонок), из-за чего вложенные элементы визуально смещаются. Utiliome автоматически преобразует все символы табуляции в равномерные пробелы в соответствии с вашими настройками.
Нормализация маркеров и исправление нумерации
Markdown поддерживает три различных символа для маркированных списков: дефис (-), звездочку (*) и плюс (+). Хотя все три варианта создают корректные HTML-элементы (<ul>), смешивание типов маркеров в одном документе создает визуальный хаос и приводит к ошибкам при автоматической проверке линтерами (например, правило markdownlint MD004).
Кроме того, нумерация упорядоченных списков часто нарушается при редактировании, когда авторы вставляют пункты в середину последовательности или используют синтаксис с повторяющимися 1.:
<!-- Неотформатированный ввод -->
* Функция A
- Функция B
+ Функция C
1. Начальный шаг
1. Второй шаг (скопирован из черновика)
4. Нарушенный порядок
Форматировщик Utiliome приводит все маркеры к выбранному вами единому символу (например, заменяет всё на -) и пересчитывает последовательности по порядку (1., 2., 3.) или приводит их к единому стилю в соответствии с правилами вашей команды.