Markdown в HTML: чистый процесс публикации

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

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

• ПереносимостьПереносимость: файл Markdown открывается в любом редакторе и преобразуется в HTML, PDF, слайды или систему документации без миграционного проекта.
• Diff-ыПрозрачность правок: изменения прозы видны как чистые построчные diff, а HTML-мастер хоронит правку одного слова внутри тегов и атрибутов.
• Структура, не стильРазделение забот: источник несёт структуру — заголовки, списки, цитаты — а типографику решает тема, поэтому редизайн никогда не трогает архив.

Продуманные конвертеры поддерживают подмножество намеренно: каждая поддерживаемая конструкция — ещё один способ протащить разметку, которую никто не проверял. Пока не положились на конвертацию, выясните, где ваш контент стоит относительно этой границы.

В режиме Markdown в HTML запись изображения сохраняет только alt-текст, а не само изображение или его URL; сырой HTML экранируется как текст. В режиме HTML в Markdown вставленная таблица превращается в ограждённый текстовый блок и теряет сетку. Проверяйте преобразованный результат до публикации.

• Чистая конвертацияЧистая конвертация: заголовки до шести уровней, абзацы, полужирный, курсив, зачёркивание, строчный код, кодовые блоки в оградах, упорядоченные и неупорядоченные списки, цитаты, горизонтальные линии и строчные ссылки.
• Известные потериЗа пределами поддерживаемого подмножества результат зависит от направления: запись изображения в Markdown сохраняет лишь alt-текст, сырой HTML в Markdown экранируется как текст, а HTML-таблицы при обратном преобразовании в Markdown становятся ограждёнными текстовыми блоками. Проверяйте сноски и списки задач в результате, не предполагая, что они сохранятся.
• Проверьте реальной статьёйПроверка проста: сконвертируйте показательную статью и прочитайте вывод. Всё, чего нет в результате, никогда не входило в контракт.

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

Панель предпросмотра рендерит очищенный вывод и никогда не загружает удалённые ресурсы, так что даже вставка вредоносной разметки не заставит сам инструмент позвонить домой.

• Активное содержимое удаленоЭлементы с активным поведением — script, style, iframe, object, embed, svg, form, video, audio, img — удаляются вместе с содержимым, а не просто обезвреживаются.
• Атрибуты срезаныСтили в атрибутах, обработчики событий и исходные классы удаляются. Безопасные ссылки сохраняют href, а корректные нумерованные списки — start.
• Отчёт, а не тишинаРабочая область отчитывается об удалённом — счётчики отброшенных узлов и срезанных атрибутов — так что санитайзинг виден, а не происходит молча.

Отрендеренный документ состоит по большей части из ссылок, и именно на ссылках санитайзинг становится конкретным. Конвертер принимает URL со схемами http, https и mailto плюс внутристраничные #фрагменты; всё остальное — javascript:, data:, протокольно-относительные трюки — теряет href и рендерится простым текстом.

Прежде чем стандартизировать конвертер, сверьте белый список со своим контентом: документации, которая законно ссылается на FTP-зеркала или собственные схемы приложений, придётся сохранять такие ссылки вручную — ни один вменяемый санитайзер не пропустит их автоматически.

• Белый список схемВыжившие ссылки помечаются rel="noreferrer noopener", так что открытая ссылка не может видеть или скриптовать страницу, с которой её открыли.
• noopener noreferrerПравило действует в обе стороны: ссылки, записанные в Markdown, проверяются при конвертации, а href из вставленного HTML перепроверяются после очистки.
• Метки выживаютКогда ссылка теряет схему, текст метки остаётся — сломанная навигация видна сразу, а не уезжает в публикацию как тихий javascript:-payload.

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

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

• Таблицы схлопываютсяТаблицы теряют сетку и превращаются в ограждённый текстовый блок, поэтому табличные данные придётся пересоздать или экспортировать в CSV.
• Медиа удаленоИзображения, видео и интерактивные вставки исчезают по дизайну — санитайзер удалил их как активное содержимое до того, как был собран Markdown.
• Текст переживает стильФорматирование вне подмножества — span, div, классы, якорные цели — не оставляет следов; текст выживает, оформление нет.

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

• Шаг в момент публикацииРабочая область принимает до 256 КиБ исходника и выдаёт до 512 КиБ результата — с запасом на главу книги — а за пределами лимитов сообщает явную ошибку, а не молча обрезает.
• Явные лимитыСкопируйте результат в поле CMS или скачайте файлом; оба пути отдают тот же очищенный документ, который показывал предпросмотр.
• Переконвертация, не заплаткиХраните Markdown в системе контроля версий рядом с кодом, который он описывает, и переконвертируйте после каждой правки вместо латания старого HTML.