YamlBox

Интернет и кодирование · 5 минута чтения

Таблицы Markdown: генерируйте их вместо подсчета труб

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

Обновлено

Синтаксис в одном примере

                | Tool          | Input       | Offline |
| :------------ | :---------: | ------: |
| YAML to JSON  | YAML        | yes     |
| JWT decoder   | JWT         | yes     |

Первая строка — это заголовок, вторая — строка-разделитель, а все, что следует за ней, — данные. Двоеточия в строке-разделителе устанавливают выравнивание: `:---` слева, `:---:` по центру, `---:` справа. GitHub и большинство средств визуализации принимают начальный и конечный канал как необязательный, но включение их позволяет сохранить необработанный текст читабельным в редакторе.

Три вещи, которые ломают столы

  • Труба внутри ячейки — экранируйте ее как `\|`, иначе строка будет слишком разделена на один столбец.
  • Строка-разделитель с неправильным количеством столбцов — заголовок смещается, и таблица отображается с перекосом.
  • Пустая строка внутри таблицы — средство визуализации воспринимает ее как конец таблицы, а остальное печатает как текст.

Экранирование наиболее важно для кода и регулярных выражений в ячейках: `a|b` и `\bfoo\b` требуют внимания, прежде чем они смогут счастливо жить внутри таблицы.

Получение данных из электронной таблицы

Естественный рабочий процесс — вставить выделенный фрагмент из электронной таблицы или экспортировать CSV и позволить генератору выполнить цитирование и выравнивание. Это быстрее и менее подвержено ошибкам, чем ввод строк, а также справляется со скучными случаями — переменной шириной столбца, числами, которые должны быть выровнены по правому краю, ячейками, содержащими запятые. Обрезайте конечные пустые столбцы перед вставкой, чтобы избежать таблицы с фантомными столбцами, которые отображаются как пробелы.

Когда не следует использовать таблицу

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

Создать, затем вставить куда угодно

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

Markdown Генератор таблиц — часто задаваемые вопросы

Как поместить символ вертикальной черты в ячейку таблицы уценок?

Экранируйте его обратной косой чертой — `\|` — иначе средство визуализации воспримет это как конец ячейки. Генераторы обрабатывают это автоматически, что является основной причиной построения таблиц с помощью инструмента, а не вручную.

Как выровнять столбец в уценке?

Используйте двоеточия в строке разделителя: `:---` для левой стороны, `:---:` для центра и `---:` для правой стороны. Выравнивание применяется ко всему столбцу, поэтому числовые столбцы выравниваются по правому краю, а текст — по левому краю, чтобы результат был наиболее читабельным.

Почему моя таблица уценки не отображается?

Проверьте три вещи: строка-разделитель имеет ровно столько же столбцов, сколько заголовок, внутри таблицы нет пустой строки, а строка заголовка непосредственно предшествует строке-разделителю. Любой из этих трех приведет к поломке рендеринга в уценке со вкусом GitHub.

Инструменты, упомянутые в этом посте

от CSV до JSON Преобразование экспорта CSV/TSV в массивы JSON или строки JSON. от JSON до CSV Преобразуйте массивы JSON в готовые для Excel файлы CSV или TSV. JSON Форматер Красиво распечатайте, минимизируйте и проверьте JSON с указанием точных местоположений ошибок. от XML до JSON Преобразуйте RSS, SOAP, карты сайта и конфигурацию XML в предсказуемый JSON.

Просмотрите полный список инструментов 19

Еще статьи для чтения

Все 19 публикации →