Генератор Markdown-таблиц

Что на самом деле представляет собой таблица Markdown

Таблицы Markdown не входят в исходную спецификацию Markdown; они пришли из GitHub Flavored Markdown — диалекта, популяризованного GitHub и теперь поддерживаемого почти везде, где пишут разработчики. Синтаксис намеренно представляет собой обычный текст: столбцы разделяются символом вертикальной черты, строка заголовка располагается сверху, а вторая строка из дефисов отделяет заголовок от тела. Поскольку это всего лишь текст, таблица Markdown остаётся читаемой в исходном виде и переживает копирование-вставку, различия в системе контроля версий и пересылку по электронной почте так, как никогда не смогла бы таблица HTML.

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

Устройство синтаксиса

Минимальная таблица выглядит как три строки. Первая строка перечисляет заголовки, разделённые вертикальными чертами, например Name, затем черта, затем Role. Вторая строка — это разделитель: по одной группе дефисов на столбец, например три дефиса, черта, три дефиса. Каждая следующая строка — это строка данных с тем же шаблоном вертикальных черт. Внешние черты в начале и конце каждой строки в GFM необязательны, но их включение делает необработанный текст проще для чтения, и именно это создаёт данный генератор.

Строка-разделитель выполняет двойную задачу: она и сигнализирует, что строка выше является заголовком, и, через расстановку двоеточий, объявляет, как выровнен каждый столбец. Вот почему таблице Markdown всегда нужны как минимум строка заголовка и строка-разделитель, чтобы вообще отобразиться.

Задание выравнивания столбцов

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

Выбор «Слева», «По центру» или «Справа» в этом инструменте расставляет за вас эти маркеры-двоеточия по всей таблице, а это значит, что выравнивание отображается одинаково на GitHub, в генераторах документации и в любом другом просмотрщике GFM, а не зависит от настроек читателя.

Разобранный пример

Вставьте три строки, разделённые запятыми: Name, Role, City сверху, а затем Ada Lovelace, Engineer, London и Grace Hopper, Admiral, New York. С выбранным выравниванием по центру инструмент выдаёт строку заголовка из трёх названий, строку-разделитель, где дефисы каждого столбца обрамлены двоеточиями, и две строки данных. Вставленная в README на GitHub, она отображается как аккуратная таблица из трёх столбцов с центрированными значениями, без ручного подсчёта вертикальных черт.

Экранирование вертикальных черт и другие подводные камни

Вертикальная черта — это разделитель столбцов, поэтому буквальная черта внутри ячейки обычно разбила бы эту ячейку надвое и испортила таблицу. Этот инструмент автоматически экранирует любую черту в ваших данных, записывая её как обратную косую черту, за которой следует вертикальная черта, так что значение вроде логического выражения с символом ИЛИ остаётся в одной ячейке и отображается как задумано.

Стоит знать ещё о двух вещах. Таблицы Markdown не могут содержать жёсткие разрывы строк внутри ячейки клавишей Enter; если внутри ячейки нужен разрыв, вы вставили бы явный тег br, поскольку GFM допускает встроенный HTML. И в каждой строке должно быть столько же столбцов, сколько в заголовке. Лишние ячейки в строке игнорируются большинством обработчиков, а недостающие отображаются как пустые, поэтому держите строки прямоугольными ради предсказуемого результата.

Разделители и значения в кавычках

Реальные данные не всегда приходят разделёнными запятыми. Если оставить разделитель в режиме «Авто», инструмент сам определит, используют ли ваши строки запятые, табуляции или вертикальные черты, а это значит, что и блок, скопированный прямо из таблицы (разделённый табуляциями), и экспорт CSV (разделённый запятыми) преобразуются без какой-либо настройки. Можно также принудительно задать конкретный разделитель, когда автоопределение угадало бы неверно, например для данных, в которых законно много запятых.

Значения CSV в кавычках тоже обрабатываются корректно. Запятая внутри двойных кавычек считается частью значения, поэтому поле вроде записи «фамилия в кавычках через запятую» остаётся в одной ячейке, а не разламывается на два столбца. Это важно, потому что экспорт из таблиц обычно заключает в кавычки любое значение, само содержащее разделитель.

Где таблицы Markdown работают, а где нет

Таблицы Markdown блистают в контексте разработки и письма: README, задачи и запросы на слияние в GitHub и GitLab; генераторы статических сайтов и документации; многие вики и приложения для заметок; чат-инструменты вроде Slack и Discord в их полях с поддержкой Markdown; и комментарии на Reddit. Везде, где поддерживается GFM, вставленная таблица просто работает и остаётся читаемой в исходном виде.

Однако они не универсальны. Обычный Markdown без расширения GFM не понимает таблиц, а некоторые облегчённые обработчики их игнорируют, и в этом случае проступают необработанные вертикальные черты. Таблицам Markdown также недостаёт точного контроля над стилями, объединённых ячеек и вложенной структуры. Когда вам нужно точное форматирование, объединение столбцов или богатое оформление, таблица HTML — лучший выбор; когда вам нужна чистая, поддающаяся контролю версий, читаемая человеком таблица, побеждает Markdown.