Переход на Markdown после 20 лет работы с HTML

alexei06/10/2025 - 08:40
Переход на Markdown после 20 лет работы с HTML

Перевод статьи Дрис Байтераерт (Dries Buytaert) "Switching to Markdown after 20 years of HTML"

Спустя почти два десятилетия и более 1600 опубликованных статей, написанных в чистом HTML, я сделал давно ожидаемый шаг: перешёл на Markdown.

Не волнуйтесь, я не отказываюсь от Drupal. Просто переключаюсь с формата "HTML-текст" на формат "Markdown".

Я писал на Markdown годами. Я начал с программы Bear для заметок, а последние четыре года пользовался инструментом Obsidian. До недавнего времени, правда, публикации в блоге выпускались мной в HTML.

Почти двадцать лет я создавал каждую статью в ручном режиме, вводя HTML-теги вручную. Написание длинных материалов могло занять у меня 45 минут, чтобы обернуть всё в теги <p>, добавить ссылки и закрыть HTML-теги, словно я вернулся в 2001 год. Работа была утомительна, но отчасти успокаивала. Я продолжал так поступать из гордости и привычки.

Получение рабочего Markdown в Drupal

Когда я решил перейти на Markdown, мне нужно было разобраться, как заставить его работать в Drupal. У Drupal есть несколько отличных модулей Markdown на выбор, но я выбрал Markdown Easy, потому что он лёгкий, полностью протестирован и построен на популярной библиотеке CommonMark.

Я описал этапы установки и обновления в публичной заметке под названием «Установка и настройка Markdown Easy для Drupal».

Единственная проблема, с которой я столкнулся, заключалась в том, что политика безопасности модуля очищала все мои HTML-теги. Это стало проблемой, потому что я чаще всего пишу на Markdown, но иногда добавляю HTML там, где Markdown не справляется, например, для кастомного оформления. Хорошим примером является создание цитат с использованием специального CSS-класса:


Через 20 лет писательства на HTML я перешел на *Markdown*.

<p class="pullquote">HTML на протяжении 20 лет. А теперь — Markdown навсегда.</p>

Теперь я могу быстрее публиковать посты, продолжая использовать [Drupal](https://drupal.org).

HTML в Markdown по задумке автора

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

HTML — это формат публикации, тогда как Markdown — формат письма. Таким образом, синтаксис форматирования Markdown касается только тех моментов, которые можно выразить обычным текстом. […] Для любого HTML-разметки, не охваченной синтаксисом Markdown, вы просто используете сам HTML. Нет необходимости предварять его или обозначать, что вы переходите от Markdown к HTML; вы просто используете соответствующие теги.

В версии Markdown Easy 1.x разрешение на использование HTML-тегов требовало создания отдельного модуля Drupal с конкретной реализацией "хука". Мне казалось, что это слишком сложная работа для того, что должно быть простым конфигурационным параметром. Я никогда не любил писать и поддерживать кастомные модули Drupal для таких случаев.

Я обратился к Майку Анелло, поддерживающему модуль Markdown Easy, чтобы обсудить более простой способ совмещения HTML и Markdown.

Я предложил сделать это конфигурационной опцией и помогал тестировать и проверять необходимые изменения. Меня радовало, когда это вошло в стандартные настройки версии 2.0. Несколько недель спустя вышла версия Markdown Easy 2.0, и теперь эта возможность доступна по умолчанию.

Теперь, когда всё заработало, я рассматриваю возможность преобразования своих существующих 1600+ статей из HTML в Markdown. Часть меня хочет видеть единый формат, но другая боится перезаписать сотни часов труда, потраченных на тонкую проработку HTML. Навязчивый перфекционист во мне спорит с архивистом. Посмотрим, кто победит.

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

Расширение Markdown токенами

Я часто совмещаю HTML и Markdown с собственными "токенами". В моём случае это не официальные веб-компоненты, но они выполняют схожую функцию.

Например, вот фрагмент, сочетающий стандартный Markdown с токеном, встраивающим изображение:


Нет ничего лучше, чем начинать день с чашечки кофе и такого вида:

[​image beach-sunrise.jpg lazy=true schema=true caption=false]

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

Настоящая сила токенов — это перспективность. Когда адаптивные изображения стали стандартом веба, я смог обновить свой процессор токенов изображений единожды и мгновенно применить улучшение ко всем моим статьям. Никакой нужды редактировать старые материалы. Точно так же произошло, когда отложенная загрузка стала стандартной, или появились новые форматы изображений. Одно изменение в коде обновило все ~10 000 изображений, которые я когда-либо публиковал.

Мои токены развивались на протяжении 15 лет и заслуживают отдельного поста в блоге. Позже я, возможно, сделаю некоторые из них полноценными веб-компонентами.

Заключительные мысли

В конечном итоге, это был не столько выбор синтаксиса, сколько принятие решения о рабочем процессе. Я хотел уменьшить трение между идеей и её публикацией. Спустя пять статей на Markdown я понял, что процесс стал быстрее, чище и приятнее, сохранив необходимую мне гибкость.

Те самые 45 минут, которые раньше уходили на ручной ввод HTML-тегов, теперь я трачу на вещи, имеющие большее значение, или на написание ещё одной статьи.