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

Четыре формата на входе, один на выходе

Таблицу Markdown легко написать и мучительно поддерживать. Добавьте в ячейку одно слово — и все вертикальные черты ниже съедут; а собрать таблицу из данных, которые у вас уже есть (результата запроса, выгрузки из таблицы, ответа API), значит перепечатать всё вручную. Этот инструмент принимает данные в том виде, в каком они у вас есть, и возвращает аккуратную таблицу в диалекте Markdown от GitHub.

Он читает четыре формата и сообщает, какой из них выбрал, а не решает молча:

• Таблицу Markdown — съехавшую таблицу достаточно вставить обратно, и она выровняется.
• CSV, разобранный по RFC 4180: поле в кавычках может содержать запятые, кавычки и даже переносы строк, и всё это уцелеет.
• TSV — то, что получается при копировании диапазона из электронной таблицы или клиента базы данных.
• Массив JSON — либо из объектов (ключи становятся столбцами), либо из массивов (первая строка становится заголовком).

Определение ищет сначала самый однозначный признак: открывающая квадратная скобка бывает только у JSON, строка из дефисов — только у разделителя Markdown, табуляция в первой строке — только у TSV. Разделение запятыми остаётся на последнем месте, поэтому оно объявляется запасным вариантом, а не находкой: если инструменту пришлось гадать, он об этом говорит, а выбор формата вручную его перекрывает.

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

Ячейка дополняется по ширине, а не по длине

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

Моноширинный шрифт — это не «один символ, одна колонка». Китайский или японский иероглиф, кана, слог хангыля, латинская буква полной ширины и почти любой эмодзи рисуются ровно вдвое шире латинской буквы. А комбинирующий знак — надстрочный акцент, огласовка в иврите, харакат в арабском — рисуется поверх предыдущей буквы и не занимает ширины вовсе. При дополнении по числу символов столбец с японским выйдет коротким, а столбец с диакритикой — длинным.

'日本語'.length          // 3  UTF-16 code units
[...'日本語'].length     // 3  code points
displayWidth('日本語')   // 6  columns in the editor

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

Одна категория намеренно считается узкой. Unicode помечает набор символов — псевдографику, некоторые греческие и кириллические буквы, ряд знаков препинания — как «неоднозначные»: широкие в старом восточноазиатском шрифте и узкие везде ещё. Файл Markdown читают в редакторе с латинским шрифтом по умолчанию, поэтому они считаются за одну колонку — ровно так, как поступают терминалы и редакторы, в которых вы этот файл откроете.

Чего таблица Markdown вместить не может

У формата два жёстких ограничения, и реальные данные упираются в оба. Ячейка не может содержать голую вертикальную черту, потому что именно она разделяет ячейки; черту приходится экранировать. А строка таблицы — это одна строка, поэтому перенос внутри ячейки невозможен в принципе, хотя поле CSV имеет на него полное право.

Переписывается и то и другое, и о каждой переписи сообщается с числом затронутых ячеек и положением первой из них. В этом и смысл: инструмент, молча превративший ваш двухстрочный адрес в одну строку, испортил данные, не сказав об этом. Перенос по умолчанию становится тегом переноса — именно так GitHub, GitLab и большинство обработчиков показывают новую строку внутри ячейки; если ваш обработчик вырезает HTML, переключите его на пробел.

Третий случай — строка длиннее заголовка. Диалект GitHub просто отбрасывает лишние ячейки, а это молчаливая потеря данных. Здесь таблица вместо этого расширяется пустыми ячейками заголовка, и о несовпадении сообщается: странно выглядящий заголовок, который можно поправить, лучше столбца, о котором вы никогда не узнаете. Строка короче заголовка дополняется пустыми ячейками и отмечается так же.

С обратными косыми чертами здесь обходятся аккуратнее, чем в большинстве инструментов. Косая удваивается только там, где она могла бы проглотить следующую за ней вертикальную черту: перед чертой в тексте или в самом конце ячейки, где дальше идёт разделитель. Во всех прочих местах она остаётся как есть, поэтому путь Windows в ячейке остаётся читаемым, а не превращается в ряд двойных косых.

Выравнивание живёт в строке-разделителе

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

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

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

С отступами или компактно, и чем отличается текст справа налево

Отступы окупаются в документе, который человек правит руками, и чего-то стоят в репозитории. Каждая выросшая ячейка перезаполняет весь свой столбец, поэтому правка одного слова попадает в diff как изменение всех строк таблицы. Компактная форма пишет самую узкую допустимую таблицу — без отступов, по три дефиса на столбец — и оставляет в diff только те строки, которые действительно изменились. Отображаются обе одинаково. Черты в начале и конце строки в диалекте GitHub не обязательны, но нужны некоторым старым обработчикам, поэтому это переключатель, а не решение.

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

По той же причине вывод Markdown на этой странице всегда показан слева направо, даже если вы читаете сайт на иврите или арабском. Это исходный код, а у исходного кода собственное направление.

Где это работает

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