Markdown в HTML: конвертация и最佳 практики

Введение

Markdown — лёгкий язык разметки, ставший стандартом для написания документации, статей, README-файлов и заметок. Его синтаксис минимален: несколько символов обозначают заголовки, списки, ссылки, выделение. Но браузеры понимают только HTML, поэтому перед публикацией Markdown нужно конвертировать. В этой статье разберём синтаксис Markdown, процесс конвертации в HTML, расширения GFM и лучшие практики использования.

Что такое Markdown

Markdown создал Джон Грубер в 2004 году как «человекочитаемый формат для веб-текста». Идея в том, чтобы текст выглядел нормально в исходном виде и без сложных преобразований превращался в HTML. Сегодня Markdown используют GitHub, GitLab, Reddit, Stack Overflow, Notion, Obsidian, Discord, Jupyter Notebook и тысячи других сервисов.

Простой пример:

# Заголовок первого уровня

Это абзац текста с **жирным** и *курсивом*.

## Подзаголовок

- Элемент списка
- Другой элемент
- [Ссылка на ConvertHub](https://converthub.ru)

Синтаксис Markdown

Заголовки

Заголовки обозначаются решётками: # — H1, ## — H2, и так до###### — H6. Многие парсеры требуют пробел после решёток. Также есть альтернативный синтаксис с подчёркиваниями для H1 и H2, но он устарел.

Выделение текста

*курсив* или _курсив_ — курсив.
**жирный** или __жирный__ — жирный.
***жирный курсив*** — оба стиля сразу.
~~зачёркнутый~~ — зачёркнутый (расширение GFM).
`код` — инлайновый код.

Списки

Маркированные списки создаются через -, * или +, нумерованные — через 1.. Вложенные уровни задаются отступами (2 или 4 пробела):

1. Первый пункт
2. Второй пункт
   - Вложенный пункт
   - Ещё вложенный
3. Третий пункт

Ссылки и изображения

[Текст ссылки](https://example.com)
[Ссылка с подсказкой](https://example.com "Подсказка")
![Alt-текст](image.png)
![Alt-текст](image.png "Подпись")

Цитаты и блоки кода

> Это цитата.
> Можно продолжить на новой строке.

```javascript
function hello() {
  console.log("Привет, мир!");
}
```

Блоки кода в тройных обратных кавычках поддерживают подсветку синтаксиса по идентификатору языка после кавычек.

Таблицы (расширение GFM)

| Колонка 1 | Колонка 2 |
|-----------|-----------|
| Значение 1 | Значение 2 |
| Значение 3 | Значение 4 |

Двоеточие в строке разделителя задаёт выравнивание: :--- — по левому краю, :---: — по центру, ---: — по правому.

GitHub Flavored Markdown (GFM)

Базовый Markdown ограничен, поэтому появились расширения. Самое популярное —GFM, стандартизированное GitHub. Оно добавляет таблицы, fenced code blocks, автоссылки, зачёркивание, списки задач и синтаксис для упоминаний.

- [ ] и - [x] — чек-боксы.
~~текст~~ — зачёркивание.
URL-адреса автоматически становятся ссылками.
@username — упоминания пользователей на GitHub.
#123 — ссылки на issues и pull requests.

Большинство современных парсеров поддерживают GFM по умолчанию, но встречаются и другие диалекты: CommonMark, MultiMarkdown, Pandoc Markdown, Markdown Extra. Они различаются поддержкой сносок, атрибутов, определения терминов и других продвинутых возможностей.

Конвертация Markdown в HTML

Онлайн-конвертер

Самый простой способ перевести Markdown в HTML — наш инструментMarkdown в HTML. Вставляете текст, выбираете расширения (GFM, подсветка кода, эмодзи), получаете готовый HTML. Все преобразования происходят в браузере, без отправки данных на сервер. Для обратной задачи естьHTML в Markdown.

Библиотеки для JavaScript

В Node.js и браузере популярны marked, markdown-it,remark, micromark. Они различаются скоростью, расширяемостью и поддержкой стандартов.

import { marked } from 'marked';

const md = '# Привет\n\nЭто **Markdown**.';
const html = marked.parse(md);

console.log(html);
// <h1>Привет</h1>
// <p>Это <strong>Markdown</strong>.</p>

Для подсветки кода в HTML используйте highlight.js илиPrism.js. Для математики (LaTeX) — KaTeX илиMathJax. Эти библиотеки интегрируются в конвейер рендеринга Markdown.

Python и другие языки

В Python используют markdown, markdown2, mistune. В Go — goldmark и blackfriday. В Ruby — kramdownи redcarpet. Все они поддерживают базовый синтаксис и расширения в той или иной степени.

Лучшие практики

Используйте GFM как современный стандарт — он поддерживается большинством инструментов и достаточно богат для большинства задач.
Разделяйте заголовки пустыми строками — иначе некоторые парсеры склеивают их с предыдущим абзацем.
Заключайте URL с подчёркиваниями в угловые скобки —<https://example.com/my_page> — иначе парсер может неправильно разобрать адрес.
Экранируйте спецсимволы, если они нужны как текст: \\*,\\_, \\#.
Указывайте язык в блоках кода — это включает подсветку синтаксиса.
Пишите осмысленный alt-текст для изображений — это помогает скринридерам и SEO.
Не злоупотребляйте HTML-вставками — это нарушает идею Markdown. Если разметки не хватает, возможно, лучше использовать HTML напрямую.

Безопасность и XSS

Markdown разрешает встраивание HTML, что открывает возможность для XSS-атак. Если контент приходит от пользователей, обязательно включайте санитизацию. В JavaScript применяйте DOMPurify или sanitize-html, в Python —bleach. Также парсеры предлагают опции отключения сырого HTML и небезопасных схем URL.

import DOMPurify from 'dompurify';
import { marked } from 'marked';

const rawHtml = marked.parse(userInput);
const safeHtml = DOMPurify.sanitize(rawHtml);

Без санитизации злонамеренный Markdown вида[click](javascript:alert('xss')) может выполнить произвольный JavaScript в браузере пользователя.

Применение Markdown

Документация проектов — README.md, CONTRIBITING.md, CHANGELOG.md в репозиториях. GitHub рендерит их автоматически.
Блоги и сайты — генераторы статических сайтов (Hugo, Jekyll, Astro, Next.js с MDX) конвертируют Markdown в HTML при сборке.
Внутренние базы знаний — Notion, Obsidian, Logseq хранят заметки в Markdown.
Комментарии и форумы — Reddit, Stack Overflow, GitHub Issues используют Markdown для форматирования сообщений.
Документация API — Swagger, OpenAPI, Redoc поддерживают Markdown в описаниях.
Презентации — Marp, Reveal.js, Slidev генерируют слайды из Markdown.

Связанные инструменты

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

Заключение

Markdown — удобный и универсальный формат для написания веб-контента. Его минималистичный синтаксис осваивается за час, а расширения вроде GFM добавляют таблицы, чек-боксы и подсветку кода. Конвертация в HTML тривиальна и автоматизирована во множестве инструментов. Если вы публикуете статьи, ведёте блог или пишете документацию, Markdown сэкономит вам часы работы. Для разовых конвертаций используйте онлайн-инструмент ConvertHub, для регулярных — статические генераторы или библиотеки вроде marked. И не забывайте про безопасность: всегда санитизируйте пользовательский Markdown от XSS.