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

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

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

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

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

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

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

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

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

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

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

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

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

Конвертация HTML в Markdown — это спасение, а не круговой рейс. Структура, понятная подмножеству, — заголовки, абзацы, акценты, списки, цитаты, код — возвращается целиком; всё остальное санитайзер выбросил ещё до начала конвертации.

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

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

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

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