DotMDКак сделать таблицу в Markdown:синтаксис, выравнивание и многострочные ячейки.
Таблица Markdown — это обычный текст: ячейки разделены вертикальными чертами, а под заголовком идёт строка из дефисов. Вот синтаксис, выравнивание столбцов и способ вставить в ячейку вертикальную черту или вторую строку.
macOS 14 или новее. Чтение бесплатно; редактирование и ревью оплачиваются один раз.
Коротко
Напишите строку заголовка, затем строку-разделитель из дефисов, затем по строке на каждую запись, с | между ячейками. Двоеточия в разделителе выравнивают столбец: :--- по левому краю, :---: по центру, ---: по правому. Чтобы показать вертикальную черту внутри ячейки, напишите \|, а для второй строки в ячейке — <br>.
| Plan | Price | Seats |
|:-----|------:|:-----:|
| Free | $0 | 1 |
| Team | $12 | 10 |·
Базовый синтаксис таблицы в Markdown
Таблицы входят в GitHub Flavored Markdown (GFM), диалект GitHub, GitLab и большинства Markdown-приложений. Для таблицы нужны три вещи:
-
Строка заголовка
Названия столбцов, разделённые вертикальными чертами:
| Name | Role |. -
Строка-разделитель
Строка из дефисов, по одной группе на столбец, прямо под заголовком:
| --- | --- |. Ячеек в ней должно быть столько же, сколько в заголовке, иначе текст останется обычным и таблицы не будет. -
Строки таблицы
По одной строке на запись, ячейки разделены вертикальными чертами. Если в строке ячеек не хватает, она дополняется пустыми, лишние отбрасываются. Таблица заканчивается на первой пустой строке.
| Name | Role |
| ----- | -------- |
| Alice | Designer |
| Bob | Engineer |Так это видит читатель:
| Имя | Роль |
|---|---|
| Алиса | Дизайнер |
| Боб | Инженер |
Вертикальные черты в начале и в конце строки необязательны, но с ними таблицу легче читать. Столбцы в исходном тексте не обязаны быть ровными: выравнивание пробелами выше нужно только людям. В ячейках можно использовать жирный, курсив, код, ссылки и изображения.
Выравнивание в таблице Markdown
Поставьте двоеточие слева, справа или с обеих сторон от дефисов столбца:
| Разделитель | Выравнивание |
|---|---|
:--- | По левому краю |
:---: | По центру |
---: | По правому краю |
--- | По умолчанию (слева в большинстве приложений) |
| Item | Qty | Price |
|:-------|:---:|------:|
| Pencil | 12 | $1.50 |
| Ruler | 3 | $4.00 || Товар | Кол-во | Цена |
|---|---|---|
| Карандаш | 12 | $1.50 |
| Линейка | 3 | $4.00 |
Выравнивание действует на весь столбец, включая заголовок. Оно задаётся один раз в строке-разделителе, а не в каждой ячейке. Числа лучше выравнивать по правому краю, чтобы разряды стояли друг под другом.
Вертикальная черта или вторая строка в ячейке
Вертикальная черта закрывает ячейку, поэтому черту, которая входит в текст, нужно экранировать обратным слэшем. GFM требует этого даже внутри строчного кода:
| Command | Meaning |
|--------------------|------------------|
| `a \| b` | a pipe, in code |
| Either \| or | a pipe, in text |В таблице на вертикальных чертах одна строка соответствует одной записи, поэтому в ячейке нельзя сделать настоящий перенос строки или второй абзац. Обычный обход — HTML-тег <br>:
| Step | What to do |
|-------|-------------------------------------|
| Build | Run the build.<br>Fix any errors. |
| Ship | Tag the release.<br>Push the tag. |Тот же приём даёт многострочную ячейку на GitHub и в большинстве других приложений, которые принимают HTML. Список Markdown в ячейке не работает: если в ячейке нужен список, поставьте <br> между короткими пунктами или вынесите список из таблицы.
Широкие таблицы и длинный текст
В Markdown нельзя задать ширину столбца или объединить ячейки: как уместить таблицу, решает приложение, которое её показывает. Несколько привычек сделают таблицу читаемой везде:
- Делайте ячейки короткими: слово или число. Длинное объяснение вынесите в предложение под таблицей.
- Берите меньше столбцов. Если их восемь, переверните таблицу: пусть столбцами будут объекты, а строками — их свойства.
- Не выравнивайте исходный текст пробелами в таблице, которую часто правите: из-за одной изменённой ячейки пришлось бы переделывать отступы во всех строках.
- Если нужны объединённые ячейки, ячейки на несколько строк или подпись, напишите таблицу на HTML. Большинство Markdown-приложений показывают обычный
<table>.
Почему таблица Markdown не отображается
- Нет строки-разделителя. Именно строка из дефисов превращает текст в таблицу.
- Число ячеек не совпадает. Если в заголовке три ячейки, а в разделителе две, ничего не отобразится.
- Неэкранированная вертикальная черта в ячейке делит её надвое. Пишите
\|. - Пустая строка внутри таблицы. На ней таблица заканчивается, остальное — обычный текст.
- В приложении нет таблиц. Таблиц нет ни в исходном Markdown, ни в ядре CommonMark. Они пришли из GFM, поэтому минимальный парсер покажет вертикальные черты как текст.
Чтобы увидеть результат до коммита, откройте файл в программе для чтения Markdown. DotMD показывает таблицы отрисованными, и читать в нём бесплатно. В DotMD Editor команда Insert → Table вставляет в файл готовую таблицу из трёх столбцов, а живой предпросмотр перерисовывает её по мере набора.
Вопросы о таблицах в Markdown
Как выровнять текст в таблице Markdown?
Добавьте двоеточия в строку-разделитель, ту, что из дефисов под заголовком. :--- выравнивает столбец по левому краю, :---: по центру, а ---: по правому.
Как сделать перенос строки в ячейке таблицы Markdown?
Напишите <br> там, где строка должна разорваться. В таблице на вертикальных чертах одна строка соответствует одной записи, поэтому настоящий перевод строки или список Markdown в ячейке не работает.
Как вставить символ вертикальной черты в ячейку таблицы?
Экранируйте его обратным слэшем: \|. Это нужно и в обычном тексте, и внутри строчного кода.
Можно ли объединять ячейки в таблице Markdown?
Нет. В таблицах GFM нет colspan и rowspan. Если нужны объединённые ячейки, напишите таблицу на HTML с <table>, colspan и rowspan.