Таблицы в Markdown: выравнивание, экранирование и важные правила
Как на самом деле работают таблицы GFM: строка-разделитель, двоеточия выравнивания, экранирование вертикальной черты и границы возможностей.
Широкую таблицу в Markdown руками пишут ровно один раз. Первую набирают аккуратно, считая вертикальные черты. Вторую вставляют из Excel и потом минут десять правят.
Обидно, потому что сам синтаксис крошечный. Почти вся боль — из-за трёх-четырёх правил, о которых нигде не предупреждают, пока не наступишь.
Строка-разделитель и есть таблица
Таблица — это строка заголовка, строка из дефисов и дальше строки с данными:
| Пакет | Версия | Назначение |
| --- | --- | --- |
| astro | 5.1.1 | статическая сборка |Уберите строку с дефисами — и таблицы больше нет. Останутся три строки текста с чертами, которые так и отрисуются. Это самая частая причина, по которой таблица в пул-реквесте выглядит как обычный абзац.
Строка заголовка ещё и намертво фиксирует число колонок. Спецификация GFM говорит об этом прямо: если в строке данных ячеек меньше, недостающие добавятся пустыми, а если больше — лишние выбросятся. Молча. Без единого предупреждения. Строка просто теряет последнюю колонку, а замечаешь ты это коммитов через пять.
Выравнивание — это двоеточия, и больше ничего
Строка с дефисами задаёт выравнивание сразу для всей колонки:
:---по левому краю:---:по центру---:по правому краю---как решит обработчик, обычно влево
Выровнять одну ячейку иначе, чем колонку, нельзя. Выровнять таблицу целиком на странице — тоже. Если нужно то или другое, вы пишете уже HTML, а не Markdown. Сталкиваются с этим нечасто, но всех, кто пришёл из Word, это удивляет.
В генераторе таблиц Markdown над каждой колонкой стоит маленький селектор: выравнивание выбирается мышью, а не вспоминается по тому, с какой стороны ставить двоеточие.
Пробелы нужны вам, а не обработчику
Выровненная таблица выглядит так:
| Пакет | Версия | Назначение |
| ----------- | ------- | ------------------ |
| astro | 5.1.1 | статическая сборка |Любой обработчик первым делом срезает пробелы внутри ячеек, так что на результат они не влияют вообще. Смысл только один: чтобы сырой файл читался, когда его открыли в редакторе. На таблице из двенадцати колонок такое выравнивание примерно удваивает размер файла и делает шумным каждый будущий diff — поэтому часть команд его отключает. Отрисовываются оба варианта одинаково, так что это вопрос вкуса.
Черта, переносы и прочие острые углы
Вертикальная черта внутри текста ячейки эту ячейку и завершает. Экранируйте её как \|, и символ отрисуется обычным. Место, на котором спотыкаются: это работает и внутри кода в обратных кавычках. Запись `a|b` в таблице всё равно разрежет ячейку, кавычки не спасают, и писать придётся `a\|b`. Спецификация GFM оговаривает это отдельным пунктом — видимо, багов на эту тему завели немало.
В ячейке живёт только строчное содержимое. Жирный шрифт, ссылки, картинки, код в кавычках — пожалуйста. Списки, заголовки, блоки кода — нет. И строка таблицы обязана уместиться в одну физическую строку файла, так что перенос внутри ячейки — это буквальный тег <br>. Некрасиво, зато работает везде, и других вариантов нет.
Соберите таблицу в сетке, а черты и экранирование оставьте инструменту. Попробуйте прямо здесь — всё считается в браузере, ничего никуда не загружается.