Синтаксис Markdown-таблиц и примеры

Минимальный синтаксис Markdown-таблицы

Первая строка содержит заголовки. Вторая строка — разделитель, превращающий блок в таблицу. Каждая следующая строка задаёт ячейки в том же порядке колонок.

| Name | Status |
| --- | --- |
| API | Ready |
| Docs | Draft |

Выравнивайте колонки двоеточиями

Поставьте двоеточие слева для выравнивания по левому краю, с обеих сторон — по центру, справа — по правому краю. Поддержка зависит от расширения таблиц, а не только от базового CommonMark.

| Left | Center | Right |
| :--- | :---: | ---: |
| A | B | 42 |

Начальный и конечный pipe необязательны, но делают исходник яснее

GFM умеет разбирать строки без внешних pipe, однако с ними границы колонок легче видеть и меньше неоднозначности при редактировании и review.

Колонки исходника не обязаны иметь одинаковую ширину

Дополнительные пробелы могут визуально выровнять исходный текст, но парсеры убирают обычные отступы вокруг содержимого ячеек. Ставьте читаемость выше идеальной ширины в символах.

Ячейки могут содержать inline Markdown

Ссылки, выделение и inline-код обычно обрабатываются внутри ячеек GFM. Блочные элементы не являются содержимым ячейки, а многострочное поведение различается между реализациями Markdown.

| Item | Reference |
| --- | --- |
| CLI | [`npm test`](https://docs.npmjs.com/) |

Экранируйте буквальный pipe внутри ячейки

Поскольку неэкранированный pipe разделяет ячейки, поставьте перед буквальным символом обратный слеш. В GFM это необходимо и внутри фрагмента inline-кода.

| Pattern | Meaning |
| --- | --- |
| `yes\|no` | Either value |

Проверьте разновидность Markdown, которая будет отображать таблицу

• GFM включает таблицы как расширение; базовый CommonMark их не определяет.
• Согласуйте количество колонок в заголовке и строке-разделителе.
• Проверьте экранированные pipe и inline-форматирование в целевом renderer.
• Используйте HTML только тогда, когда место назначения его разрешает, а Markdown не может выразить нужную разметку.