Markdown в HTML: практическое руководство для авторов и разработчиков

Markdown придумал Джон Грубер в 2004 году — идея была простая: писать для веба, не открывая HTML-теги. Набираешь **жирный**, и что-то превращает это в жирный. Несложно. Но это «что-то» должно где-то существовать, и понимание того, как работает конвертация, реально экономит время, когда результат выглядит не так, как ожидалось.

Что происходит при конвертации

Конвертер Markdown в HTML читает текст построчно. Он ищет паттерны: строка, начинающаяся с #, становится <h1>, **текст** оборачивается в , дефис в начале строки превращается в <li> внутри <ul>.

Важен порядок обработки. Жирный (**текст**) и курсив (*текст*) используют один и тот же символ — звёздочку. Нормальный парсер правильно обрабатывает ***жирный курсив***, обрабатывая трёх-звёздочный паттерн раньше двух-звёздочного, а тот — раньше однозвёздочного. Ошибка в порядке — непредсказуемый вывод.

Ещё один момент: что происходит с HTML-тегами внутри Markdown? Одни конвертеры пропускают их без изменений, другие экранируют. Конвертер Markdown в HTML экранирует:   на входе становится   на выходе. Это безопаснее по умолчанию, особенно когда результат попадает в систему, которая не фильтрует вставляемый контент.

Типичные сценарии использования

Редакторы CMS — самый очевидный случай. Ghost, Notion и многие блог-платформы позволяют писать в Markdown и хранят отрендеренный HTML в базе. При миграции между платформами часто нужно переконвертировать исходный Markdown — и важно видеть, что именно получится на выходе.

Email-шаблоны — менее очевидный случай. HTML-письма писать вручную утомительно. Написать в Markdown и сконвертировать — это хотя бы даёт чистую структуру для начала. Инлайн-стили для почтовых клиентов всё равно придётся добавлять, но разметку за вас сделает конвертер.

README на GitHub рендерится автоматически, но GitHub-рендерер не идентичен каждому парсеру. Если предпросмотр в репозитории выглядит странно, сырой HTML помогает понять — проблема в Markdown или в том, как шаблон обрабатывает вывод.

Генераторы статических сайтов — Astro, Hugo, Jekyll — конвертируют Markdown в момент сборки. Когда что-то выглядит не так, проверка промежуточного HTML подсказывает, где проблема: в исходнике или в шаблоне.

Синтаксис, который ломает ожидания

Смешанные списки — частый источник проблем. Пустая строка между элементами списка включает оборачивание в абзацы: каждый <li> получает внутри . Одни конвертеры делают это, другие — нет. Если ваш CSS обращается к li напрямую и не рассчитывает на вложенный , вёрстка поломается.

Блоки кода с указанием языка — ```js — добавляют class="language-js" к элементу <code>. Именно это соглашение используют подсветчики синтаксиса Prism и Highlight.js. Если вставляете HTML на страницу с одной из этих библиотек, тег языка в Markdown — всё, что нужно.

Инлайн-HTML: как уже сказано, этот конвертер экранирует HTML-теги на входе. Если нужен  или <kbd> в выводе, большинство парсеров пропустят сырой HTML — но экранирование по умолчанию предотвращает случайные инъекции, когда результат попадает в систему без собственной фильтрации.

Когда браузер быстрее

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

Для продакшна автоматическая конвертация в пайплайне — правильный выбор. Но чтобы проверить, что Markdown даст на выходе перед коммитом, или когда вы работаете на чужой машине без привычных инструментов, браузерный вариант справляется.

Вставьте Markdown в конвертер Markdown в HTML и посмотрите предпросмотр рядом с HTML-кодом — без регистрации и установки.