HTML в Markdown: очистка контента для статей

Введение

HTML — родной язык веба, но для написания и редактирования статей он избыточен. Теги засоряют текст, мешают фокусироваться на содержании и усложняют перенос между системами. Markdown решает эту проблему: компактный, читаемый, легко превращается обратно в HTML. Когда у вас уже есть HTML-контент (например, импортированный из CMS, почтового рассыльщика или скопированный со страницы), его полезно очистить до Markdown. В этой статье разберём, зачем и как конвертировать HTML в Markdown, какие сложности возникают и какие инструменты выбрать.

Зачем конвертировать HTML в Markdown

• Миграция контента — перенос статей из WordPress, Drupal или Medium в статические генераторы сайтов (Hugo, Astro, Jekyll), где Markdown — основной формат.
• Очистка для редактирования — HTML-письма и веб-страницы часто содержат лишние теги, встроенные стили и атрибуты. Markdown оставляет только семантику.
• Хранение в Git — Markdown-файлы удобно диффать, ревьюить и версионировать. HTML генерирует шум в diff из-за обилия тегов.
• Кросс-платформенность — Markdown поддерживают Notion, Obsidian, GitHub, Slack, Discord. HTML — далеко не везде.
• Подготовка к публикации — многие CMS принимают Markdown, а HTML фильтруют или обрезают.
• Перенос в базы знаний — Confluence, Notion, Obsidian импортируют Markdown лучше, чем сырой HTML.

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

Markdown принципиально беднее HTML: в нём нет атрибутов, классов, встроенных стилей, сложной вложенности. При конвертации часть информации теряется:

• Атрибуты class, id, style — отбрасываются.
• <div>, <span> без семантики — удаляются.
• Сложные таблицы с объединёнными ячейками (colspan, rowspan) — упрощаются.
• Встроенные стили — теряются, остаётся только семантическое форматирование.
• Скрипты, формы, iframe — обычно отбрасываются из соображений безопасности.
• Специфические теги (<details>, <figure>) — превращаются в базовые конструкции.

Это особенность, а не недостаток: Markdown задумывался как семантический формат, где важна структура, а не оформление. Если вам критично сохранить стили, Markdown не подойдёт — оставайтесь в HTML.

Сопоставление тегов

Инструменты конвертации

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

Для разовых задач удобен наш инструмент HTML в Markdown: вставляете HTML, выбираете диалект Markdown (CommonMark, GFM), получаете готовый текст. Поддерживаются настройки сохранения или удаления атрибутов, обработки изображений и таблиц. Для конвертации в чистый текст без форматирования есть HTML в TXT.

Библиотеки

• JavaScript — turndown (самая популярная, расширяемая через плагины), html-to-md.
• Python — markdownify, html2text.
• Ruby — reverse_markdown.
• Go — html-to-markdown от Johannes Kaufmann.
• CLI — pandoc универсальный конвертер между десятками форматов.

Пример с turndown

import TurndownService from 'turndown';
import * as turndownPluginGfm from 'turndown-plugin-gfm';

const turndown = new TurndownService({
  headingStyle: 'atx',
  codeBlockStyle: 'fenced',
  bulletListMarker: '-',
});
turndown.use(turndownPluginGfm.gfm);

const html = '<h1>Заголовок</h1><p>Текст с <strong>выделением</strong>.</p>';
const md = turndown.turndown(html);

console.log(md);
// # Заголовок
//
// Текст с **выделением**.

Сложные случаи

Таблицы

HTML-таблицы с объединёнными ячейками (colspan, rowspan) не имеют прямого аналога в Markdown. Парсеры либо разбивают их на несколько простых таблиц, либо теряют объединения. Также могут возникнуть проблемы с таблицами, у которых нет <thead>: GFM требует строку заголовков.

Изображения

В HTML у <img> может быть title, width,height, loading="lazy". В Markdown сохраняется толькоalt и src, опционально title. Если важны размеры, придётся либо потерять их, либо использовать HTML-вставку внутри Markdown.

Вложенные списки

HTML допускает произвольную вложенность списков и других элементов. Markdown строже: списки можно вкладывать друг в друга, но смешивание с блочными элементами (цитатами, блоками кода) требует осторожности с отступами. Парсеры справляются по-разному.

Спецсимволы

HTML-сущности (&, <) нужно превратить в символы и, при необходимости, экранировать в Markdown. Например, символ* в тексте Markdown нужно превратить в \\*, иначе парсер воспримет его как начало выделения.

Блоки кода с HTML

Если внутри <pre><code> лежит HTML-код, нужно либо преобразовать его в Markdown-блок с экранированием, либо оставить как есть. Хорошие конвертеры различают эти случаи.

Очистка от мусора

HTML из CMS и редакторов часто содержит мусор: пустые <div>, инлайновые стили из Word, лишние <br>, невидимые символы. Перед конвертацией в Markdown полезно провести санитизацию:

• Удалить теги <script>, <style>, <iframe>.
• Снять атрибуты class, style, id, кроме нужных.
• Заменить <br> на переносы строк или удалить.
• Слить подряд идущие <p> в один абзац, если между ними нет семантики.
• Удалить Unicode-символы вроде неразрывных пробелов, где они не нужны.
• Преобразовать <font> и другие устаревшие теги в современные.

В JavaScript для этого используют sanitize-html илиDOMPurify с кастомной конфигурацией. В Python — bleach илиlxml.html.clean.

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

• Сохраняйте важные атрибуты — если используете якоря для оглавления, оставляйте id на заголовках.
• Проверяйте результат на сложных местах — таблицы, списки в цитатах, блоки кода.
• Используйте GFM как целевой формат — он поддерживает таблицы, зачёркивание, чек-боксы.
• Документируйте конвертацию — сохраняйте оригинальный HTML в архиве, чтобы при необходимости восстановить потерянные данные.
• Запускайте линтер на результате — markdownlint найдёт проблемы с отступами, заголовками и ссылками.
• Не пытайтесь сохранить всё — Markdown философски отличается от HTML. Если что-то не помещается, оставьте как HTML-вставку.

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

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

Заключение

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