Отступы Markdown: вложенные списки, абзацы и код
Исправляйте отступы Markdown по примерам вложенных и нумерованных списков, дополнительных абзацев и ограждённого кода. Избегайте случайных блоков кода.
Чтобы задать отступ вложенного списка Markdown, расположите его маркер под первым символом текста родительского пункта. Для - Родительский пункт это два пробела, для 1. Родительский пункт три. Отступы управляют структурой документа, поэтому пробелы перед обычным абзацем могут давать совсем другой результат, чем изменение визуального отступа абзаца Word.
Начните с этого примера в просмотрщике Markdown:
- Документы проекта
- Руководство по установке
- Примечания к выпуску
- Контрольный список проверки
Руководство по установке и примечания к выпуску должны появиться внутри пункта документов проекта. Контрольный список проверки должен остаться на внешнем уровне.
Считайте от начала содержимого родительского пункта
Для обычных пунктов с одним пробелом после маркера используйте эту таблицу выравнивания:
| Начало родительского пункта | Символов перед его текстом | Отступ вложенного списка |
|---|---|---|
- | 2 | 2 пробела |
1. | 3 | 3 пробела |
12. | 4 | 4 пробела |
100. | 5 | 5 пробелов |
Поэтому общее правило вроде «всегда используйте два пробела» не работает для нумерованных списков. В документации GitHub о вложенных списках показано выравнивание относительно содержимого родительского пункта, включая длинные числовые маркеры.
1. Подготовить выпуск
- Подтвердить номер версии.
- Обновить журнал изменений.
2. Опубликовать документацию
Перед вложенными маркерами стоят три пробела. Если они начинаются у левого края, то образуют отдельный список и не относятся к первому нумерованному шагу.
Если вы работаете со старым обработчиком Markdown, проверьте файл и в нём. Эти примеры ориентированы на разбор в стиле CommonMark и GitHub Markdown; старые реализации могут иначе распознавать вложенные блоки.
Добавьте абзац внутри пункта списка
Длинному пояснению не нужен отдельный маркер. Оставьте пустую строку, затем выровняйте новый абзац под текстом пункта:
1. Проверить руководство по установке.
Убедиться, что новый читатель может выполнить настройку,
не открывая внутренний документ.
2. Утвердить примечания к выпуску.
Поясняющий абзац относится к первому шагу. Две его строки исходника идут подряд, если не добавить явный перенос строки.
Отсутствие трёх пробелов может завершить нумерованный список и превратить пояснение в обычный абзац. В некоторых сценариях редактирования это также приводит к тому, что нумерация следующего списка начинается заново.
Тот же шаблон работает для маркированных списков:
- Руководство по установке
Указать предварительные требования, команды настройки и шаг проверки.
- Примечания к выпуску
Используйте отдельный абзац, если пояснение содержит несколько предложений. Используйте вложенный список, если в нём есть самостоятельные пункты, которые читателям удобно просматривать по отдельности.
Поместите код внутрь нумерованного шага
Ограждённый блок кода делает границы примера команды явными. Сделайте отступ у открывающего ограждения, содержимого и закрывающего ограждения, чтобы блок оставался внутри пункта:
1. Проверить установленную версию.
```sh
node --version
```
Записать результат в заметки проверки.
2. Выполнить проверки проекта.
Здесь ограждение начинается под первой буквой слова Проверить. Абзац после ограждения выровнен так же, поэтому тоже остаётся внутри первого шага.
Если следующий нумерованный шаг становится частью блока кода, проверьте закрывающее ограждение. Если код появляется вне списка, проверьте пробелы перед ограждением. Метки языков и буквальные обратные кавычки описаны в руководстве по блокам кода.
Почему четыре пробела могут превратить текст в код
На внешнем уровне документа после пустой строки четыре пробела перед строкой могут создать отступный блок кода:
Обычный абзац.
Эта строка отображается как код.
Это предусмотренный синтаксис Markdown, а не поломка управления отступами. Роль отступов и границ блоков объясняется в справочнике CommonMark по отступным блокам кода.
Для строки с отступом непосредственно после обычного текста абзаца действуют другие ограничения разбора, поэтому вставка пробелов не является надёжным способом создать визуальный отступ абзаца. Внутри списков требуемое количество пробелов также отсчитывается относительно содержащего пункта.
Для цитирования используйте блок цитаты. Если обычному тексту в итоговом отчёте нужен отступ первой строки, оставьте в Markdown обычный абзац и примените форматирование абзаца в Word после экспорта. Эти варианты сохраняют задуманный смысл содержимого.
При поиске ошибок предпочитайте пробелы
Табуляция может занимать несколько экранных столбцов, а разные редакторы могут отображать её с разной шириной. Если список выглядит выровненным в исходнике, но отображается неправильно, включите показ пробельных символов и замените начальные табуляции нужным количеством пробелов.
Не заменяйте табуляции внутри примеров кода без разбора. Там пробельные символы могут быть частью самого примера. Ограничьте очистку маркерами Markdown и отступами продолжений, определяющими окружающую структуру списка.
Не имитируйте вложенный список повторяющимися сущностями неразрывного пробела. В одном предпросмотре текст может выглядеть сдвинутым, хотя сам документ останется набором не связанных друг с другом абзацев.
Проверьте структуру перед экспортом в Word
Проверьте характерный раздел с родительским пунктом, вложенным списком, вторым абзацем и ограждённым блоком кода. В конвертере Markdown в HTML настоящий вложенный список содержится внутри родительского пункта; одно визуальное смещение не устанавливает эту связь.
Затем используйте конвертер Markdown в Word и откройте DOCX. Убедитесь, что нумерация продолжается как задумано, а команды остаются связаны со своими шагами. Стили списков Word могут задавать иные визуальные интервалы, чем браузер, поэтому перед отправкой оцените и иерархию, и внешний вид итогового документа.