Markdown - это формат, в котором я пишу почти все - README, документация плагина, примечания к выпуску, описания запросов на извлечение, журнал изменений для WP Adminify, половина моих внутренних заметок. Он уходит с дороги для каждой конструкции, кроме одной. В тот момент, когда задействована таблица, я прекращаю писать и начинаю подсчет символов трубы, и поток уходит. Добавьте столбец в пятирядную таблицу, и вы редактируете шесть строк вручную, плюс строку разделителя, и вы не узнаете, правильно ли вы ее получили, пока страница не будет отображаться.
TL;DR: выше Генератор таблиц Markdown дает вам сетку в стиле электронной таблицы, генерирует действительную GitHub Flavored Markdown по мере ввода и импортирует CSV, вставку электронной таблицы или существующую таблицу Markdown, чтобы вы могли ее реструктурировать. Установите выравнивание по столбцам одним щелчком мыши и экспортируйте Markdown, HTML или CSV. Все работает в вашем браузере.
Инструмент существует, потому что синтаксис таблицы является единственной частью Markdown, где исходный формат активно борется с редактированием. это руководство охватывает как работают таблицы GFM, правила, которые решают, ваши рендеры, ускользающие ловушки, которые разбивают строки, и как использовать генератор для рабочих процессов таблицы обычно приходят из - электронной таблицы, результата запроса, или таблицы кто-то уже написал.
Что такое таблица Markdown?
Таблица Markdown - это три ингредиента, сложенные в фиксированном порядке: строка заголовка, строка разделителя и ноль или более строк тела. Таблицы вообще не являются частью основной Markdown - они являются расширением, определяемым Спецификация GitHub Flavored Markdown, именно поэтому таблица может отображаться на GitHub и выходить в виде буквальных трубок в другом месте. ячейки разделены символами-трубами, и каждая строка занимает ровно одну строку.
| Tool | Category | Offline |
| --- | --- | --- |
| JSON Formatter | Coding | Yes |
| YAML to JSON | Data | Yes |
Строка разделителя - это та часть, которая делает его таблицей, а не абзацем, содержащим трубы. Это должна быть вторая строка, она должна состоять из дефисов с необязательными двоеточиями, и она должна иметь такое же количество ячеек, как и заголовок. Получите что-либо из этого неправильно, и рендерер рассматривает весь блок как обычный текст - поэтому & quot;моя таблица отображается как простой текст" почти всегда является проблемой разделителя строк.
Таблицы не являются частью первоначальной спецификации CommonMark. Они прибыли как расширение GitHub Flavored Markdown и впоследствии были приняты почти везде: GitHub, GitLab, Bitbucket, Obsidian, Notion, Docusaurus, MkDocs, VitePress, Hugo, Jekyll, Discord, и большинство генераторов статических сайтов. & quot;Almost & quot; является оперативным словом. Минимальный средство рендеринга CommonMark без расширений покажет вашу таблицу как литеральные каналы, и исправление заключается в том, чтобы вместо этого выдавать HTML - что генератор может сделать одним щелчком мыши на вкладках вывода.
Почему синтаксис труднее поддерживать, чем кажется
Читать таблицу Markdown легко Поддерживать один - это то, где скрывается стоимость, и он приходит из четырех мест.
Структура живет в пунктуации. Нет границы ячейки, кроме символа, который также появляется в регулярных выражениях, командах оболочки и типах объединения TypeScript. Каждый из тех, кто находится внутри ячейки, должен быть экранирован, или строка молча получает столбец.
Выравнивание кодируется в расположении толстой кишки. Двоеточие слева означает левое выравнивание, двоеточие с обеих сторон означает центрированное, двоеточие справа означает правое выравнивание. нет ключевого слова, по которому можно было бы запомнить его, и разницы между ними ---: а :--- это один персонаж подряд, которого никто близко не читает.
Редактирование многострочное. Добавление столбца означает касание каждой строки плюс разделитель. переупорядочение строк означает вырезание и вставку без визуальной обратной связи. Удаление столбца - это поиск n-й трубы на каждой строке.
Выравнивание источника ручное. Мягкие столбцы не требуются - рендереры игнорируют дополнительные пробелы - но несложенные таблицы плохо читать в различии, поэтому люди заполняют их вручную, а затем повторно заполняют каждый раз, когда содержимое ячейки и №39;s растет.
Редактор сетки удаляет все четыре. Вы редактируете ячейки; генерируется синтаксис. Это вся предпосылка инструмента.
Как использовать Генератор таблиц Markdown
Шаг 1: Получите данные в сетку
Три маршрута, в зависимости от того, где уже живут данные.
Введите это. Сетка открывается заполненным образцом. перезапишите ячейки или нажмите "Очистить" для пустого изображения три на три и начните все сначала.
Вставить из электронной таблицы. Откройте панель Импорт и вставьте скопированный диапазон из Excel, Google Sheets, Numbers или LibreOffice.Spreadsheets поместите текст, разделенный вкладками, в буфер обмена, и импортер обнаружит, что автоматически - нет необходимости указывать ему, какой разделитель вы используете.
Вставить CSV или существующую таблицу. Эта же панель принимает CSV, экспорт с разделением по полуколоннам (по умолчанию во многих европейских регионах), текст с разделением каналов и таблицы разметки. Если текст выглядит как таблица разметки - строка заголовка, за которой следует строка разделителя - он анализируется как единое целое, включая выравнивание столбцов, поэтому вы можете загрузить таблицу из README, реструктурировать ее и вставить обратно.
Импорт CSV следует правилам RFC 4180, а не наивно разделяется на запятых. поле с кавычками может содержать запятые, разрывы строк и удвоенные кавычки, которые обозначают буквальный символ кавычки. Это имеет большее значение, чем звучит: любой экспорт, содержащий адрес, описание или цену в локали, использующей запятые, нарушит наивное разделение, и вы не заметите, пока колонка не станет короткой на одну ячейку. Если ваш CSV достаточно велик, чтобы вы хотели проверить его перед импортом, CSV-просмотр сначала открывает его в сортируемой сетке.
Шаг 2: Сформируйте стол
Органы управления вокруг сетки охватывают операции, которые болезненны при необработанной разметке:
- Роу а Столбец добавить в конец сетки.
- Стрелки рядом с каждой строкой перемещают ее вверх или вниз - полезно для заказа таблицы сравнения по тому, что вы решили важнее всего.
- Кнопка минус в заголовке строки или столбца удаляет его сразу в каждой строке.
- Транспонировать меняет местами строки и столбцы. Данные, вставленные из отчета, часто ориентируются неправильно для документа, а транспонирование - один щелчок вместо полного повторного ввода.
Шаг 3: Установите выравнивание для каждого столбца
Каждый заголовок столбца содержит три кнопки выравнивания: левая, центральная, правая. Нажмите один, чтобы применить его, щелкните его еще раз, чтобы вернуться к рендереру и #39;s по умолчанию. Генератор записывает соответствующие двоеточия в строку разделителя.
Выравнивание стоит использовать намеренно. Числовые столбцы - цены, подсчеты, проценты, продолжительность - читаются гораздо лучше вправо, потому что цифры выровнены по значению места. Короткие значения статуса выглядят аккуратно по центру. Текст принадлежит левому. Это не украшение; выровненный вправо столбец чисел действительно быстрее сканировать на предмет наибольшего значения.
Шаг 4: Выберите выходной формат и скопируйте
Три вкладки вывода:
Уценка производит GFM. The Мягкие колонны переключение контролирует, заполнены ли ячейки пробелами, поэтому необработанный источник выстраивается в моноширинный редактор. Наполнение ничего не меняет в том, как отображается таблица - это исключительно для тех, кто читает файл в различии. Наружные трубы управляет ведущей и задней трубой в каждом ряду; оба стиля действительны, и стиль ведущей трубы является гораздо более распространенным соглашением.
HTML производит а <table> с <thead> а <tbody> и рядный text-align стили, соответствующие выравниванию столбцов. Используйте его для рендереров, которым не хватает поддержки таблиц, для шаблонов электронной почты или когда вам нужно colspan и многострочные ячейки, которые Markdown не может выразить Если вы хотите пойти в другом направлении и поднять таблицу из веб-страницы, HTML-маркет обрабатывает это.
CSV возвращает вам сетку в виде данных, правильно цитируемых, для вставки в электронную таблицу или подачи в сценарий.
Скопируйте в буфер обмена или загрузите как .md, .html, или .csv пилка
Правила побега, которые фактически ломают таблицы
Два символа вызывают почти каждую разбитую таблицу разметки, и оба обрабатываются генератором автоматически, но вы должны знать правила для таблиц, которые редактируете вручную.
Труба. Буквальный канал внутри ячейки должен быть записан как \|. Без обратной косой черты средство рендеринга видит разделитель столбцов, и ваша строка получает ячейку, отбрасывая каждый столбец после нее. Это сильнее всего кусается в технической документации, где ячейки законно содержат такие вещи, как string | null, grep foo | wc -l, или изменение regex.Escape работает даже внутри обратных кодовых пролетов - редкий случай, когда Markdown's обычное & quot;кодовые пролеты буквальны" правило не применяется.
Новая линия. Таблицы GFM представляют собой строго одну строку на строку, поэтому ячейка не может содержать реальный разрыв строки. Универсальный обходной путь - это HTML <br> тег. при вставке многострочного контента в сетку генератор вставляет для вас тег; при импорте таблицы, содержащей <br>, он преобразуется обратно в реальный разрыв строки в редакторе, поэтому ячейку удобно редактировать.
Еще два правила стоит зафиксировать в памяти, потому что они вызывают & quot;моя таблица не отображает & quot; отчеты, которые не имеют ничего общего с самой таблицей. во-первых, таблица нуждается в пустой строке перед ней, когда она следует за абзацем. во-вторых, внутри элемента списка вся таблица должна быть отступать к элементу списка и #39;s столбец контента - в противном случае список поглощает первую строку, и строка разделителя приземляется в неправильном месте.
Откуда берутся таблицы и как течет каждый случай
Электронная таблица, которую вам прислали
Скопируйте диапазон, вставьте в панель "Импорт", загрузите его в сетку, удалите столбцы, которые никому не нужны, выровняйте числовой, скопируйте Markdown. Менее минуты для таблицы, для ручного формата которой потребуется десять.
Результат запроса или ответ API
Данные, которые начинаются как JSON, обычно нуждаются в одном прыжке. Преобразуйте его с помощью json в CSV, затем вставить CSV в импортер.Going the other way - Markdown table you need as data - экспортировать CSV из выходных вкладок и запустить его через CSV в JSON, йо-
Таблица, которая уже существует в README
Вставить его в панель Импорт.Он возвращается в сетку с неповрежденными выравниваниями, поэтому добавление столбца или переупорядочение строк - это обычное редактирование, а не перезапись. это рабочий процесс, который я использую чаще всего: таблицы документации растут по одной строке в течение нескольких месяцев, затем нуждаются в реструктуризации сразу.
Таблица сравнения, которую вы пишете с нуля
Начните с сетки, введите, как вы думаете, и позвольте заполнению разобраться в себе. Запись сравнения в сетке, а не в синтаксисе трубы, удерживает ваше внимание на том, справедливо ли сравнение, а не на том, совпадают ли столбцы.
Документация, которая должна работать в нескольких рендерерах
Создайте Markdown для платформ, поддерживающих таблицы GFM, затем переключите вкладку вывода на HTML для той, которая не поддерживает. та же сетка, два экспорта, без перепечатки. если ваш конвейер все равно преобразует Markdown в HTML, Markdown на HTML показывает вам, что именно дает преобразование.
Таблицы разметки против таблиц HTML
| любовное | Таблица разметки | Таблица HTML |
|---|---|---|
| Читаемость источника | Высокий - сканируется как обычный текст | Низкий - теги доминируют над контентом |
| Многострочные ячейки | Только через <br> |
Родной, любой контент блока |
| Объединённые ячейки | не поддерживается | colspan а rowspan |
| Выравнивание по столбцам | Да, через разделители | Да, через CSS или атрибуты |
| Управление стилем | ни один | Полный CSS |
| Поддержка рендерера | Расширение GFM широко распространено, но не универсально | Универсально везде, где разрешен HTML |
| Различное дружелюбие | Хорошо, по одной строке в ряд | Бедно, много строк в строке |
Практическое правило: используйте Markdown до тех пор, пока вам не понадобится объединенная ячейка, элемент блока внутри ячейки или определенный стиль. Затем переключите эту таблицу на HTML и оставьте остальную часть документа в покое. большинство рендереров Markdown пропускают необработанный HTML, поэтому смешивание двух в одном файле - это нормально.
Заметка о конфиденциальности
Таблицы, которые люди создают, часто предпочитают не загружать: цены еще не объявлены, численность персонала, внутренние тесты, клиент и данные №39;s, вставленные из электронной таблицы.
Генератор является клиент-сторона JavaScript. сетка, анализатор импорта, и каждый экспортный запуск на странице, и ничто из того, что вы вставляете, не покидает вашу машину. загрузите его один раз, и он продолжает работать в автономном режиме. это тот же принцип, что и все на Toolz.dev, и рассуждения стоит прочитать полностью в руководстве на Конфиденциальность данных в онлайн-инстру. Если вы собираете более широкий набор браузерных утилит для повседневной работы, Руководство по инструментам кодирования и тот Набор инструментов для веб-разработчиков прикройте то, что еще приносит закладку.
Практические советы
Держите заголовок коротким. При включении заполнения самая широкая ячейка в столбце устанавливает ширину каждой строки в источнике. Многословный заголовок делает необработанный файл зашумленным без выгоды от рендеринга.
Не бойтесь недополненного вывода сгенерированных файлов. Если таблица написана сценарием и никогда не читается как исходный код, выключите заполнение и сохраните байты.
Сортировать перед вставкой. Переупорядочение строк по одному щелчку стрелки за раз подходит для пяти строк и утомительно для пятидесяти. сначала сортируйте в электронной таблице, затем импортируйте.
Смотрите для пустого ряда заголовка. С & quot;Первая строка - заголовок& quot; выключен, генератор выдает пустой заголовок над вашими данными, потому что у GFM нет возможности выразить таблицу без заголовка Некоторые рендереры показывают, что как тонкая пустая строка Если это беспокоит вас, экспортируйте вместо этого HTML, который вообще не нуждается в заголовке.
Проверьте отображаемый результат, а не источник. Добавленный источник, который выглядит идеально, все равно может отобразить неправильно, если строка разделителя имеет неправильное количество ячеек. Вставьте в предварительный просмотр любой платформы, на которой вы публикуете, прежде чем называть это сделанным.
часто задаваемые вопросы
Как создать таблицу в Markdown?
Таблица Markdown нуждается в строке заголовка, строке разделителя дефисов и одной строке на запись, с ячейками, разделенными символами трубы. Заполните сетку в генераторе, и инструмент напишет для вас этот синтаксис, включая строку разделителя и любые двоеточия выравнивания.
Как выровнять столбцы в таблице Markdown?
Выравнивание устанавливается с помощью двоеточий в разделительной строке: двоеточие слева выравнивается влево, двоеточия с обеих сторон - в центре, а двоеточие справа выравнивается вправо. Выберите выравнивание из заголовка столбца в редакторе, и правильное размещение двоеточия будет сгенерировано автоматически.
Могу ли я преобразовать диапазон Excel или Google Sheets в таблицу Markdown?
да. Скопируйте ячейки в таблицу и вставьте их в панель импорта. Электронные таблицы размещают текст, разделенный вкладками, в буфер обмена, который импортер автоматически обнаруживает и загружает в сетку.
Как поместить символ трубы внутри ячейки таблицы?
Буквальный канал должен быть экранирован с обратной косой чертой или рендерер будет читать его как разделитель столбцов. Введите трубу нормально в редакторе и генератор выходит из нее в выходе для вас.
Может ли ячейка таблицы Markdown содержать несколько строк?
Не с реальными новострочными строками, потому что таблицы GFM - это строго одна строка на строку Обычный обходной путь - это тег разрыва строки HTML внутри ячейки, который этот инструмент вставляет автоматически, когда вставляемая ячейка содержит разрыв строки.
Почему моя таблица отображается как обычный текст на GitHub?
Строка разделителя почти всегда является причиной: это должна быть вторая строка и она должна иметь такое же количество ячеек, как и заголовок. Отсутствующая пустая строка перед таблицей также может остановить ее рендеринг, когда таблица следует за абзацем или находится внутри списка.
Должен ли я прокладывать столбцы, чтобы исходный код выстраивался?
Нет. Рендереры игнорируют дополнительные пробелы, поэтому таблица без подкладки отображается одинаково. Подкладка существует для людей, читающих необработанный файл в редакторе или диф. Выключите ее с помощью мягкого переключателя вывода, если вы предпочитаете компактный исходный код.
Поддерживаются ли таблицы Markdown везде?
Таблицы являются расширением GitHub Flavored Markdown, а не частью исходной спецификации CommonMark. GitHub, GitLab, Obsidian, Notion, Docusaurus и большинство генераторов статических сайтов поддерживают их, но некоторые минимальные рендереры этого не делают. Переключите вывод на HTML, если ваш один из них.
