Таблицы Markdown: синтаксис, выравнивание и советы

Что такое таблицы Markdown?

Таблицы Markdown используют символы вертикальной черты (|) и дефисы (-) для создания структурированных табличных данных в текстовых документах. Они являются частью GitHub Flavored Markdown (GFM) и поддерживаются большинством рендереров Markdown, включая GitHub, GitLab, VS Code и генераторы статических сайтов.

Таблицы в Markdown предназначены для простого представления данных — заголовки столбцов, строка-разделитель и строки данных. Они отображаются как корректные HTML-таблицы в выводе, что делает их идеальными для документации, README-файлов и технических текстов без знания HTML.

Синтаксис таблиц Markdown

Таблица Markdown состоит из трёх частей: строки заголовка, строки-разделителя и одной или нескольких строк данных.

• Строка заголовка — первая строка определяет названия столбцов, разделённые символами вертикальной черты (|). Начальные и конечные черты необязательны, но рекомендуются для ясности.
• Строка-разделитель — вторая строка использует дефисы (---) между вертикальными чертами для отделения заголовка от данных. Требуется не менее трёх дефисов на столбец.
• Строки данных — каждая последующая строка содержит значения ячеек, разделённые вертикальными чертами. Ячейки не обязаны быть выровнены визуально, хотя выровненные столбцы улучшают читаемость исходного кода.
• Экранирование вертикальных черт — если содержимое ячейки содержит символ вертикальной черты, экранируйте его обратным слешем (\|), чтобы предотвратить его интерпретацию как разделителя столбцов.

Параметры выравнивания столбцов

Выравнивание столбцов управляется добавлением двоеточий в строку-разделитель. Это определяет выравнивание текста внутри каждого столбца.

• Выравнивание по левому краю (по умолчанию) — используйте :--- или --- в разделителе. Текст выравнивается по левому краю столбца. Это значение по умолчанию, когда двоеточия не указаны.
• Выравнивание по центру — используйте :---: в разделителе. Текст центрируется внутри столбца. Полезно для меток статуса, категорий или коротких значений.
• Выравнивание по правому краю — используйте ---: в разделителе. Текст выравнивается по правому краю. Идеально для числовых значений, цен, счётчиков и измерений.

Распространённые случаи использования

Таблицы Markdown используются везде, где структурированные данные необходимо представить в документации.

• Документация README — таблицы сравнения функций проекта, требования к установке, поддерживаемые платформы и матрицы совместимости версий
• Документация API — справочник эндпоинтов с методом, путём, описанием и таблицами параметров для каждого маршрута
• Сравнительные таблицы — сравнение функций рядом, ценовые уровни и оценки инструментов в блогах и технических обзорах
• Журналы изменений — таблицы истории версий с датой, номером версии и описанием изменений для каждого релиза

Советы и лучшие практики

Соблюдение этих рекомендаций помогает поддерживать читаемость таблиц Markdown как в исходном коде, так и в отображённой форме.

• Сохраняйте выравнивание столбцов в исходном коде — дополняйте ячейки пробелами, чтобы столбцы визуально совпадали. Большинство редакторов и наш генератор делают это автоматически. Выровненный исходный код значительно легче проверять в pull request-ах.
• Избегайте сложного содержимого в ячейках — таблицы Markdown не поддерживают многострочное содержимое ячеек, блочные элементы или вложенные таблицы. Держите содержимое ячеек коротким и простым. Для сложных данных рассмотрите использование HTML-таблиц.
• Ограничивайте количество столбцов — таблицы с более чем 5-6 столбцами становятся трудночитаемыми на небольших экранах. Рассмотрите разбиение широких таблиц на несколько целевых таблиц или использование другого формата для очень широких данных.

Часто задаваемые вопросы

Есть ли ограничение на содержимое ячеек в таблицах Markdown?

Технического ограничения символов для содержимого ячеек нет, но ячейки таблиц Markdown поддерживают только одну строку. Внутри ячейки нельзя использовать переносы строк, абзацы или блочные элементы вроде списков. Для сложного содержимого ячеек используйте HTML-таблицы с элементами <td>, которые поддерживают любое HTML-содержимое.

Можно ли объединять ячейки в таблицах Markdown?

Нет. Стандартные таблицы Markdown не поддерживают colspan или rowspan — каждая строка должна иметь одинаковое количество столбцов. Объединение ячеек требует HTML-таблиц. Если вам нужны объединённые ячейки, напишите таблицу в HTML и вставьте её прямо в документ Markdown.

Можно ли вкладывать таблицы в таблицы Markdown?

Нет. Таблицы Markdown не могут быть вложенными. Каждая таблица — это плоская сетка строк и столбцов. Если вам нужны иерархические данные, рассмотрите вложенные списки, отдельные таблицы с заголовками или HTML-таблицы с вложенными элементами <table>.