Таблицы в Markdown: синтаксис GFM, выравнивание и ограничения
Таблицы GFM с разделителями «|», выравнивание и ограничения по ячейкам.
Таблица в формате Markdown — это строка заголовка, строка-разделитель из дефисов и строки данных под ней. Именно строка-разделитель превращает вертикальные черточки в таблицу в GFM и в Hugo.
Это руководство является частью раздела Инструменты для документации в 2026 году: Markdown, LaTeX, PDF и процессы печати. Другие типы блоков описаны в Шпаргалке по Markdown.
Таблицы отсутствуют в исходной синтаксисе Markdown и в CommonMark. Это расширение для таблиц в спецификации GitHub Flavored Markdown. Hugo 0.164 использует Goldmark, где это расширение включено по умолчанию (markup.goldmark.extensions.table). Примеры ниже заключены в разделители, чтобы вертикальные черточки оставались литеральными; это тот же паттерн, что и в разделе Кодовые блоки в Markdown.
Синтаксис таблицы с вертикальными черточками
Таблица состоит из трёх частей: одной строки заголовка, одной строки-разделителя и нуля или более строк данных. Ячейки разделяются символом |. Вертикальная черта в начале и в конце строки является необязательной. Пробелы рядом с вертикальной чертой удаляются.
| Заголовок 1 | Заголовок 2 |
| --- | --- |
| Ячейка A1 | Ячейка B1 |
| Ячейка A2 | Ячейка B2 |
В документах по написанию текста на GitHub указано, что в каждой ячейке строки-разделителя должно быть не менее трёх дефисов, а пустая строка перед таблицей обязательна для её корректного отображения на GitHub. Спецификация GFM описывает ячейку строки-разделителя как набор дефисов, где двоеточие может стоять с любой из сторон, а среди примеров есть ячейка с одним дефисом. Hugo 0.164 отобразил это как таблицу:
| A | B |
| - | - |
| 1 | 2 |
Тот же рендеринг в Hugo также превратил таблицу в <table>, когда предыдущей строкой был абзац и пустая строка отсутствовала. На GitHub следуйте правилу трёх дефисов в разделителе и использованию пустой строки. На этом сайте достаточно одного дефиса, а пустая строка не требуется.
Фрагмент |Слишком|Близко| с разделителем |---|---| также был отрендерен. Пробелы рядом с вертикальными чертами удаляются. Пробелы в первом примере сохранены, чтобы обеспечить читаемость диффов в исходном коде.
Строка заголовка и строка-разделитель должны содержать одинаковое количество ячеек. Если их количество различается, Hugo не распознаёт таблицу. В этом случае содержимое остаётся обычным текстом, и дефисы становятся кандидатами для типографа Hugo:
| abc | def |
| --- |
| bar |
Строка данных может быть короче или длиннее строки заголовка. Короткая строка дополняется пустыми ячейками. Ячейки, превышающие количество ячеек в заголовке, отбрасываются.
| A | B | C |
| --- | --- | --- |
| 1 | 2 |
| A | B |
| --- | --- |
| 1 | 2 | 3 |
Первая из этих таблиц отрендерит пустую третью ячейку. Вторая отрендерит только 1 и 2.
Строка без вертикальных черточек всё равно находится внутри таблицы до пустой строки. Hugo 0.164 включил следующее слово bar в таблицу как строку с пустой второй ячейкой, что соответствует примеру 202 спецификации GFM. Следующий абзац начинается после пустой строки.
| abc | def |
| --- | --- |
| bar | baz |
bar
next
Выравнивание столбцов
Выравнивание задаётся двоеточием в строке-разделителе. --- без двоеточия означает выравнивание по левому краю, что то же самое, что и :---.
| Слева | Справа | По центру |
| :--- | ----: | :----: |
| текст | 12.50 | да |
| Слева | Справа | По центру |
|---|---|---|
| текст | 12.50 | да |
Двоеточия в строке заголовка — это просто символы в этой ячейке. Они не задают выравнивание. Именно строка-разделитель ниже используется Hugo для определения выравнивания:
| :--- Слева | Справа ---: |
| :-------- | ---------- |
| Верно | Выравнивание |
Содержимое ячеек
Внутри ячейки работают инлайновые элементы: курсив, код и ссылки. Блочные конструкции не работают. Спецификация GFM гласит, что блочные элементы нельзя вставлять в таблицу, поэтому список или кодовый блок внутри ячейки не являются ни списком, ни код-фенсом.
| Функция | Статус | Документация |
| ---------- | ---------- | ------------- |
| **API v2** | *Выпущено* | [Доки](/api) |
| `Auth` | Бета | Скоро |
Буквальный символ вертикальной черты — это \| или |. Hugo 0.164 отрендерил оба как |.
| Выражение | Результат |
| ---------- | ------ |
| a | b | true |
| x \| y | false |
Перенос строки внутри ячейки — это HTML-тег <br>. На этом сайте параметр markup.goldmark.renderer.unsafe установлен в значение true, поэтому этот тег сохраняется. Обработчик, удаляющий сырой HTML, объединяет две половины в одну строку.
Три дефиса, написанные как текст в ячейке, — это отдельная ловушка в Hugo. Типограф переписывает --- в ячейке в тире (—). Код-спан сохраняет дефисы. \--- отрендерился как -–.
| Как текст | Как код |
| ------- | ------- |
| --- | `---` |
Слияние ячеек
В GFM нет атрибутов rowspan или colspan. Когда ячейка должна покрывать две строки, таблица должна быть в формате HTML. Нестрогий рендерер этого сайта оставляет этот HTML в странице:
<table>
<tr>
<td rowspan="2">Слияние</td>
<td>Ячейка 1</td>
</tr>
<tr>
<td>Ячейка 2</td>
</tr>
</table>
Записыватель Pandoc markdown+pipe_tables выводит синтаксис с вертикальными черточками для этой страницы. Этот записыватель используется при конвертации документов Word в Markdown. Сеточные таблицы и другие раскладки, существующие только в Pandoc, являются особенностями диалекта, они описаны в разделе GFM против CommonMark против Pandoc Markdown.
Широкая таблица с вертикальными черточками прокручивается или выходит за пределы экрана. Переносимые способы уменьшения включают транспонированную раскладку, несколько более мелких таблиц или HTML-таблицу с собственным CSS. В синтаксисе с вертикальными черточками нет подписи к таблице. Содержимое страницы (TOC) в Hugo строится из заголовков.
Проверки, если таблица остаётся текстом
Посчитайте количество ячеек в строке заголовка и в строке-разделителе. Если эти два числа различаются, блок остаётся абзацем. Короткая строка данных всё равно является частью таблицы, и в конце добавляется пустая ячейка. Правило markdownlint MD056 требует, чтобы каждая строка соответствовала этому количеству, потому что короткая строка выглядит как отсутствующая ячейка, а лишняя ячейка отбрасывается.
Осмотрите строку-разделитель на наличие двоеточий. Двоеточие, стоящее в заголовке, является текстом, и столбец остаётся выровненным по значению, указанному в строке-разделителе.
Если --- внутри ячейки отображается на этом сайте как одиночный дефис, значит, типограф переписал его. Поместите дефисы в код-спан.
Если GitHub отображает вертикальные черточки как текст, добавьте пустую строку, которую требуют документы GitHub, и используйте не менее трёх дефисов в каждой ячейке строки-разделителя. Hugo 0.164 уже принимал более короткую форму.
Отсутствующая строка-разделитель — это другой случай, когда блок с вертикальными черточками остаётся текстом. Hugo 0.164 оставил это как абзац:
| Заголовок 1 | Заголовок 2 |
| Ячейка A | Ячейка B |
Таблица параметров
Одна и та же строка-разделитель задаёт выравнивание и оставляет место для инлайнового кода:
| Параметр | Тип | По умолчанию | Обязательно |
| :-------- | :------ | :-----: | :------: |
| `apiKey` | string | — | Да |
| `timeout` | number | 30000 | Нет |
| `retries` | number | 3 | Нет |
