Зачем преобразовывать Markdown в HTML
Markdown — лёгкий язык разметки, дружелюбный к автору, но браузеры понимают только HTML. Содержание, написанное в Markdown, для показа на веб-странице нужно преобразовать в HTML.
Типичные сценарии:
- Публикация статей в блоге
- Рендеринг сайтов документации
- Показ README
- Экспорт HTML из rich-text редакторов
Соответствие синтаксиса Markdown и HTML
Заголовки
Markdown:
# Заголовок 1
## Заголовок 2
### Заголовок 3
HTML:
<h1>Заголовок 1</h1>
<h2>Заголовок 2</h2>
<h3>Заголовок 3</h3>
Абзац
Markdown: текстовые абзацы, разделённые пустой строкой.
HTML: <p>абзац</p>
Выделение
Markdown:
**жирный**
*курсив*
~~зачёркнутый~~
HTML:
<strong>жирный</strong>
<em>курсив</em>
<del>зачёркнутый</del>
Ссылка
Markdown:
[текст ссылки](https://example.com)
HTML:
<a href="https://example.com">текст ссылки</a>
Изображение
Markdown:
HTML:
<img src="image.png" alt="альтернативный текст">
Списки
Markdown неупорядоченный список:
- Пункт 1
- Пункт 2
HTML:
<ul>
<li>Пункт 1</li>
<li>Пункт 2</li>
</ul>
Markdown упорядоченный список:
1. Первый пункт
2. Второй пункт
HTML:
<ol>
<li>Первый пункт</li>
<li>Второй пункт</li>
</ol>
Код
Markdown строчный код:
Это `code` строчный код
HTML: Это <code>code</code> строчный код
Markdown блок кода:
блок кода
HTML:
<pre><code>блок кода</code></pre>
С подсветкой языка:
```javascript
const x = 1;
После преобразования включает разметку подсветки синтаксиса (нужна библиотека подсветки).
### Цитата
Markdown:
Это цитата
HTML:
```html
<blockquote>Это цитата</blockquote>
Горизонтальная линия
Markdown:
---
HTML:
<hr>
Таблица
Markdown:
| Имя | Возраст |
| ---- | ------- |
| Tom | 25 |
HTML:
<table>
<thead>
<tr><th>Имя</th><th>Возраст</th></tr>
</thead>
<tbody>
<tr><td>Tom</td><td>25</td></tr>
</tbody>
</table>
Расширенный синтаксис
Стандартный Markdown (CommonMark) не включает перечисленные ниже возможности, но большинство парсеров их поддерживает:
Список задач
- [x] Выполнено
- [ ] Не выполнено
HTML:
<ul>
<li><input type="checkbox" checked disabled> Выполнено</li>
<li><input type="checkbox" disabled> Не выполнено</li>
</ul>
Сноски
Текст[^1]
[^1]: Содержание сноски
Зачёркивание
~~зачёркнуто~~
Автоссылки
URL автоматически превращается в ссылку (не нужно вручную писать ).
Списки определений, оглавление, формулы и т. п.
Поддерживаются некоторыми парсерами, совместимость различается.
На что обратить внимание при преобразовании
Потеря стилей
Преобразование Markdown в HTML генерирует только теги, без стилей. Внешний вид зависит от CSS:
- Размер и отступы заголовков
- Отступы и маркеры списков
- Фон и шрифт блоков кода
- Рамки таблиц
После преобразования нужно добавить CSS, чтобы выглядело красиво.
Безопасность от XSS
Markdown позволяет встраивать HTML. При преобразовании пользовательского Markdown в HTML встроенные теги вроде <script> сохраняются, что приводит к XSS.
Безопасные практики:
- Используйте чистый Markdown (отключите встроенный HTML)
- После преобразования в HTML фильтруйте опасные теги библиотекой sanitize
- Допускайте Markdown только из доверенных источников
Escape-символы
Специальные символы Markdown (, #, _, ) требуют экранирования. Запись *в Markdown отображает звёздочку; после преобразования в HTML это`, а не тег.
Пути к изображениям
Изображения с относительными путями в Markdown сохраняют путь после преобразования в HTML. При смене каталога показа настройте путь.
Якорные ссылки
Заголовки Markdown автоматически создают якоря (id). У разных парсеров правила различаются — учитывайте это при ссылке на якоря.
Инструменты преобразования
Онлайн-преобразование
Вставьте Markdown, и инструмент выведет HTML. Подходит для разового преобразования.
Используйте инструмент Markdown в HTML:
- Вставьте содержимое Markdown
- Инструмент разберёт и преобразует
- Выведет HTML-код
- Скопируйте и используйте
Преобразование в браузере, содержание не отправляется.
Интеграция с редакторами
Редакторы вроде VS Code и Typora имеют встроенный предпросмотр Markdown в HTML.
Программное преобразование
В JavaScript используйте библиотеки marked или markdown-it. В Python — markdown или mistune.
Советы по преобразованию
Унифицируйте стиль Markdown
Разные диалекты Markdown (CommonMark, GFM, MDX) могут давать разные результаты. Команде следует выбрать один диалект.
Предпросмотр и проверка
После преобразования предварительно просмотрите в браузере и проверьте:
- Корректна ли иерархия заголовков
- Нормально ли вложение списков
- Подсвечен ли блок кода
- Выровнена ли таблица
- Отображается ли изображение
- Кликабельна ли ссылка
Сопутствующий CSS
Подготовьте CSS для рендеринга Markdown; примените его к сгенерированному HTML для красивого отображения.
Сохраняйте исходный Markdown
HTML — результат рендеринга, Markdown — исходный файл. Сохраняйте Markdown для последующего редактирования, а HTML регенерируйте каждый раз заново.
Часто задаваемые вопросы
После преобразования стиль неверный
У HTML нет CSS. Добавьте таблицу стилей рендеринга Markdown.
Блок кода без подсветки
Нужна библиотека подсветки синтаксиса (например, highlight.js или Prism). Интегрирует ли инструмент подсветку — зависит от конфигурации.
Сдвиг таблицы
Синтаксис таблиц Markdown нестрогий (число столбцов может не совпадать). Проверьте формат таблицы перед преобразованием.
Спецсимволы отображаются странно
Символы < > & в Markdown имеют особый смысл в HTML. Их нужно экранировать в < > &.
Итоги
Суть преобразования Markdown в HTML — отображение соответствия синтаксиса. Обратите внимание на сопутствующий CSS, безопасность от XSS и экранирование спецсимволов. Инструмент Markdown в HTML от DocsAll работает в браузере, содержание не уходит наружу.