Markdown в HTML: Что на самом деле происходит, когда ваш readme будет визуализирован

Я писал Markdown каждый рабочий день в течение многих лет - плагины README, журналы изменений, документы Toolz.dev, заметки о выпуске для WP adminify, половина сообщений фиксации. И большую часть этого времени я рассматривал шаг рендеринга как магию. Вы пишете звездочки, GitHub показывает жирный. хорошо Двигайтесь дальше.

Затем я создал раздел Docs, который вывел из базы данных Markdown и отобразил его на страницу Next.js, и магия превратилась в список очень конкретных решений, которые мне нужно было принять. Становится ли одна новая строка <br>? (Комментарии GitHub говорят да. Спецификация Markdown говорит, что нет.) дурак <div> В исходном рендеринге как div или как литературный текст? (Зависит, кто спрашивает, и доверяете ли вы автору.) Какой класс идет на огороженный блок кода, чтобы хайлайтер его улавливал? Почему один синтаксический анализатор поворачивается **bold**text на жирный, а другой оставляет это в покое?

Ничто из этого не является экзотическим. Это просто то, что вам никто не говорит, потому что уценка выглядит настолько просто, что люди предполагают, что под ним ничего нет. Под ним довольно много. выше Markdown на HTML Конвертер на Toolz.dev раскрывает эти решения как коммутаторы, а не скрывая их, какую версию этого инструмента я хотел, когда я отлаживал, почему мои разрывы строк не исчезали.

TL;DR: Markdown - это формат письма; HTML - это формат отображения. Что-то должно компилировать одно в другое. Правила, которые сбивают людей с толку: последовательные строки объединяются в один абзац, если вы не закончите строку двумя пробелами (или не включите "breaks" опция), необработанный HTML либо передается, либо экранируется в зависимости от параметров доверия парсера's, а диалект GitHub's (GFM) добавляет таблицы, списки задач, зачеркивание и автосвязь с открытым URL-адресом поверх общая метка базовый уровень. Огороженный код компилируется в <pre><code class="language-js">, который является призмой крючков, Highlight.js и Shiki ищут. выше Markdown в HTML-конвертер Все это делает в вашем браузере, с открытыми коммутаторами.

Что такое Markdown и зачем вообще нужно конвертировать?

Markdown - это синтаксис в виде открытого текста, опубликованный Джоном Грубером в 2004 году, с одной заявленной целью дизайна: документ Markdown должен публиковаться как есть, читаться как обычный текст, не выглядя так, будто он помечен тегами. Вот почему синтаксис заимствован из соглашений, которые люди уже использовали в электронной почте - звездочки вокруг слова для выделения, строка тире под заголовком, a > за цитату.

Следствием является то, что уценка не является форматом рендеринга. Ничто не отображает уценку. Браузеры отображают HTML, и все места, где вы когда-либо увиденный Отображение Markdown - GitHub, статический сайт, портал документов, приложение для чата - сначала запустил синтаксический анализатор и поместил HTML на экран.

Так что преобразование должно где-то произойти. Ваши варианты примерно:

• во время сборки, в генераторе статического сайта или упаковщике. Хорошо, когда контент живет в вашем репозитории.
• в срок, на сервере. Необходим, когда контент поступает из базы данных, дорогостоящий, если вы делаете это по каждому запросу без кэширования.
• в браузере, в данный момент вам это нужно. Это то, что вы хотите, когда ответ на «Мне просто нужен HTML-код для этой вещи» — это копи-паста, а не конвейер сборки.

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

В чем разница между CommonMark и Github со вкусом Markdown?

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

Github со вкусом Markdown (GFM) это формальный супермножество commonmark, заданное GitHub, которое добавляет то, о чем люди постоянно просили:

Если ваш Markdown был получен из GitHub readme, вики GitLab, экспорта понятий или большинства современных редакторов, то это GFM. Включите GFM в конвертере или ваши таблицы будут отображаться как буквальные трубы, что является номером один, «преобразователь сломался», — вопрос поддержки любого, кто поставляет один из этих инструментов, получает.

Почему пропала моя линия?

Поскольку Markdown, следуя соглашениям обычной электронной почты, рассматривает последовательные непустые строки как один абзац. ЭТО:

Line one
Line two

производит <p>Line one\nLine two</p>- один абзац, и новая строка сворачивается в пространство, когда браузер ее отображает. Это не ошибка; это спецификация, и она существует для того, чтобы вы могли жестко обернуть свою прозу в 80 столбцов текстового редактора, не допуская утечки этой упаковки в выходные данные.

Есть три способа получить реальный перерыв:

1. пустая строка Начинает новый абзац. Это то, что вы хотите большую часть времени.
2. Два прохода в конце строки произвести жесткий разрыв - <br />, йо- Это стандартный трюк, и он невидим в вашем редакторе, поэтому люди находят его сводящим с ума.
3. обратная косая черта В конце строки делает то же самое в CommonMark и, по крайней мере, видно.

И тогда есть четвертый путь, который является источником путаницы: Многие платформы включают режим "перерывы" где каждая новая строка становится <br />, йо- GitHub комментарии и проблемы делают это. Большинство чат-приложений делают это. Файлы GitHub Readme нет, йо- Таким образом, один и тот же текст отображается по-разному в проблеме GitHub и в README того же репозитория, что является действительно плохой частью дизайна, с которой мы все теперь застряли.

Конвертер выставляет это как коммутатор. Если ваш источник был написан для рендерера в стиле чата, включите обрывы строки. Если это документ, оставьте его и используйте пустые строки, как это задумал.

Как обрабатывается RAW HTML?

Markdown разрешает встроенный HTML - исходная спецификация явно говорит, что любой HTML, который вы пишете, проходит прямо через. Это функция, когда вы являетесь автором (вы хотите свой <details> Блок, твой <img> С атрибутом ширины ваш якорь с rel), и это ответственность, когда вы не являетесь.

Потому что, если вы отрисовываете ненадежный Markdown с включенным сквозным сквозным HTML, у вас есть уязвимость XSS. <script>alert(document.cookie)</script> является действительным уценкой. так <img src=x onerror="...">, йо- Так же <a href="javascript:...">. Поле для комментариев, биография профиля пользователя, общедоступная вики - где бы незнакомцы ни писали "Уценка", которую читают другие люди - должны либо выйти из HTML, либо очистить выходные данные с помощью настоящего дезинфицирующего средства (DOMPurify - обычный ответ, и это настоящий дезинфицирующий средство именно потому, что регекса недостаточно для враждебного ввода).

Этот конвертер по умолчанию беглый Сырой HTML: <div> в вашем источнике отображается как буквальный текст <div> В выходе точно так же, как если бы вы написали <div>, йо- Вы можете включить сквозное сквозное использование, когда источник ваш. И независимо от этой настройки, живой превью получается <script>, <style>, встроенный on* обработчики событий и javascript: URL-адреса перед рендерингом - мера защиты по глубине, поэтому вставка кого-то другого's README в панель предварительного просмотра не может выполнить их код. Это мера предварительной безопасности, а не дезинфицирующее средство общего назначения: если вы создаете продукт, который отображает пользователя Markdown, используйте выделенную серверную часть дезинфицирующего средства и не доверяйте регексу, включая мой.

Если вам нужно избежать персонажа из Уменьшите, чтобы это отображалось буквально - звездочка, которая должна оставаться звездочкой, подчеркивание в имени файла - обратная косая черта делает это: \*not emphasis\*, йо- И если вы обсуждаете сущности в другом направлении, то Кодировщик/декодер сущностей HTML является инструментом для этой работы.

Какой HTML должен действительно излучать хороший конвертер?

Семантический, скучный, бесклассовый HTML - за одним исключением.

• Заголовки становятся <h1>-<h6>, йо- С включенными идентификаторами заголовков каждый также получает наклонное id, дедупликация, когда две заголовки имеют общий заголовок (#setup, #setup-1). Это то, что делает #anchor Глубокие ссылки работают, и это то, что висит генератор таблицы содержимого.
• Огороженный блок с информационной строкой - ```js- становится <pre><code class="language-js">, йо- *Это исключение.* * Язык-` Класс — это конвенция призма, Highlight.js и Shiki все ищут, и именно поэтому конвертер вообще излучает класс. Конвертер не раскрашивает ваш код, маркировка на вашей странице, и ему нужен этот крючок.
• Списки становятся <ul>/<ol>, а вот и тонкость, которую стоит знать: скудный Список (нет пустых строк между элементами) помещает текст прямо внутри <li>, в то время как небрежный Список (пустые строки между элементами) Оборачивает содержание каждого элемента в <p>, йо- Это поведение CommonMark, а не причуда, и именно поэтому ваш список внезапно увеличивается по вертикали, когда вы добавляете пустую линию между двумя пулями. CSS не сломался, HTML действительно изменился.
• Столы становятся реальными <table>/<thead>/<tbody> разметка, с style="text-align:center" на ячейках, когда строка разделителя используется :---:, йо-
• Списки задач становятся <input type="checkbox" disabled> внутри <li>, что именно то, что Github излучает.

Content-Infir, никаких div-оберток, нет классов служебных данных. Вы его стилизовали со стороны, с .prose класс или ваши собственные правила, и разметка остается портативной.

Как использовать конвертер?

Шаг 1: Вставьте уценку

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

Шаг 2: Установите переключатели

Github со вкусом Если в источнике есть таблицы, списки задач или зачеркивание (вероятно, это так). Идентификаторы заголовка на, если вы хотите якоря. обрывы строк Вкл., только если источник был написан для рендерера в стиле чата. Разрешить необработанный HTM Вкл, только если источник твой. полный документ Вкл., если вы хотите полную страницу HTML5 с DocType, Charset, Viewport и <title> взято из вашего первого <h1>- полезно, когда вы хотите открыть результат непосредственно в браузере или разместить его на статическом хосте.

Шаг 3: Проверьте предварительный просмотр

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

Шаг 4: Возьмите вывод

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

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

Общие варианты использования

Получение README на веб-сайт

Авторы плагина и пакета пишут хороший readme, а затем нуждаются в том же контенте на целевой странице. README — это GFM с таблицами и значками; целевой странице нужен HTML. Конвертируйте, вставьте, стиль с существующим CSS. Идентификаторы заголовка дают вам БС на боковой панели бесплатно.

Публикация в CMS, которая принимает только HTML

Множество полей CMS, почтовых платформ и устаревших панелей администраторов принимают HTML и ничего больше. если вы черновите в Markdown - а большинство людей, которые пишут регулярно делают - это мост. конвертировать с полный документ OFF, так что вы получаете фрагмент, а не целую страницу, и вставляете его в поле.

Прототипирование страницы документов

Прежде чем зафиксировать содержимое на сайте DOCS, его локальное преобразование показывает вам фактическую иерархию заголовка и нужны ли ваши заборы кода. выше h3 это должно было быть h2 Явна в TOC и невидимы в источнике.

Аудит контента, который написал кто-то другой

Вставьте вкладчик's Markdown, посмотрите на испускаемый HTML, и вы сразу увидите, использовали ли они реальные заголовки или выделили жирным шрифтом строку, чтобы подделать его - привычка, которая разрушает структуру документа и доступность. Считыватели экрана перемещаются по заголовку; **Big Text** Это не заголовок, это абзац, выделенный жирным шрифтом, и конвертер показывает вам, что в одной строке вывода.

Извлечение оглавления

Длинным документам нужен один, и его поддержание вручную гарантирует, что он устареет. Сгенерируйте его из заголовков, вставьте, регенерируйте, когда заголовки меняются.

Дополнительно: что делает этот синтаксический анализатор и не делает

Это рукописный анализатор, примерно 400 строк, без зависимостей, что является преднамеренным, поскольку анализатор Markdown, который перетягивает зависимость размером 200 КБ на страницу, вся суть которой заключается в быстроте, является плохой сделкой.

покрытый: ATX заголовки (# x) и заголовки сет (подчеркнутые с === / ---), абзацы, акцент и сильный (*, _, **, __), встроенный код с сопоставлением с обратным ходом, огражденный код с информационными строками, блоками с отступом, блочные цитаты с ленивым продолжением, вложенные списки (заказанные и незаказанные, плотные и свободные), тематические перерывы, ссылки и изображения с заголовками, автоссылками на угловые скобы, автоссылками на электронную почту, наборы обратных слепков: таблицы со списком задач, ссылки на заголовки, скучно-ударные автосвязывание.

Не покрываются: Ссылки в стиле ссылок ([text][ref] с [ref]: url Определение в другом месте), сноски, списки определений и несколько действительно смущающих угловых случаев вокруг блоков HTML, прерывающих абзацы. Если вы используете набор CommonMark Conformance Suite, он не будет набирать 100%. Если вы преобразовываете README, журнал изменений или сообщение в блоге, вы этого не заметите.

Это честная сделка, и именно поэтому преобразователь загружается мгновенно и работает с сетью. Для конвейеров контента, где вам нужно точное соответствие CommonMark, используйте markdown-it, remark или cmark В вашей билде, для этого они и нужны.

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

Как преобразовать markdown в html?

Вставьте Markdown в редактор, и HTML появится немедленно - нет кнопки конвертировать и нет файла для загрузки.Включите GitHub Flavored Markdown, если ваш источник использует таблицы или списки задач, затем скопируйте HTML или загрузите его как файл.html. Все работает в вашем браузере, поэтому неопубликованные черновики и внутренние документы никогда не покидают ваше устройство.

Что такое Markdown со вкусом Github?

GitHub со вкусом Markdown (GFM) — это формально заданный супермножество CommonMark, который добавляет таблицы, флажки списка задач, зачеркивание с двойными тильдами и автоматическую связь голых URL-адресов. Это диалект GitHub использует для рендеринга файлов и проблем README, и это то, что сегодня издает большинство редакторов Markdown. По умолчанию он включен в этом конвертере.

Почему исчезла моя однострочная перерыв?

Стандартная маркдаун соединяет последовательные строки в один абзац; разрыв строки сохраняется только в том случае, если вы оканчиваете строку с двумя пробелами, используете конечную обратную косую косую или оставляющую пустую строку. Если вы хотите, чтобы каждая новая строка стала <br />, включить опцию разрыва строки - это поведение GitHub комментарии и большинство чат приложений используют, но это не то, что README файлы делают.

Конвертер выделяет мой код?

Он излучает разметку, в которой нуждается хайлайтер, но не окрашивает сам код. Огороженный блок кода с тегом язык js становиться <pre><code class="language-js">, который является классовой призмой, Highlight.js и Shiki все ищут. Добавьте одну из этих библиотек на страницу, в которую вы вставите вывод, и выделение появится автоматически.

Сохранен ли RAW HTML внутри моего Markdown?

По умолчанию он сбежит, поэтому <div> отображается как буквальный текст, а не тег. Включите опцию "разрешить-обновить-HTML" для пропуска тегов прямо, что вам нужно, когда ваша Markdown намеренно смешивается в HTML - a <details> блокировать или изображение с атрибутами. Включите его только для источника, которому вы доверяете, потому что RAW HTML от ненадежного автора — это вектор XSS.

Безопасно ли вставлять уценку, которую я не писал?

Да. HTML экранируется по умолчанию, и предварительный просмотр в реальном времени дополнительно удаляет теги сценариев и стилей, встроенные обработчики событий и URL-адреса javascript: перед рендерингом. Ничто из вставленного вами продукта нигде не передается. Если вы создаете продукт, который отображает Markdown от незнакомцев, все равно используйте специальный дезинфицирующий аппарат, такой как сервер DOMPurify - фильтр предварительного просмотра не заменяет его.

Могу ли я создать оглавление из своих заголовков?

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

Этот конвертер полностью реализует CommonMark?

Он реализует конструкции, которые люди фактически пишут - ATX и setext заголовки, абзацы, акценты, ссылки, изображения, автоссылки, блок-цитаты, вложенные и свободные списки, огороженный и отступы код, тематические разрывы, обратные косые экраны - плюс расширения GFM. ссылки, сноски в стиле ссылки и несколько редких случаев ребер HTML-блока CommonMark не охвачены. для битового соответствия в конвейере сборки используйте markdown-it, memark или cmark.

Связанные инструменты: Markdown на HTML · HTML-объект · HTML-минификатор · счетчик слов · генератор пуль

Связанное чтение: Набор инструментов для веб-разработчика · Руководство по текстовым инструментам