Markdown для AI-агентов: кейс плагина Roots для WordPress

Современные AI-агенты и языковые модели эффективнее обрабатывают Markdown, чем HTML. Разметка Markdown содержит меньше токенов, лишена «хрома» темы и не требует парсинга вложенных тегов. Однако большинство SEO-плагинов, заявляющих поддержку Markdown для AI, игнорируют HTTP-заголовок Accept и продолжают возвращать HTML независимо от запроса. Это приводит к тому, что AI-инструменты получают перегруженный код вместо чистого контента, а владельцы сайтов не могут контролировать представление своих материалов для машин.

Перед разработчиками из команды Roots стояла задача: дать WordPress-сайтам возможность корректно отдавать посты в Markdown, соблюдая стандарты согласования контента и не создавая отдельных API-эндпоинтов. Результатом стал плагин Post Content to Markdown, который решает проблему на уровне HTTP и внутренней конвертации блоков.

Решение: плагин Post Content to Markdown

Плагин добавляет Markdown-представление для каждого поста и фида WordPress. Он не требует настройки отдельных маршрутов — достаточно активировать его, и все существующие записи сразу получают альтернативное представление. Клиенты могут запросить Markdown тремя способами:

через заголовок Accept: text/markdown (основной метод для AI-агентов и скриптов);
через query-параметр ?format=markdown;
через суффикс .md в URL, например /hello-world.md.

HTML-версия поста автоматически рекламирует Markdown-альтернативу с помощью HTTP-заголовка Link: rel="alternate"; type="text/markdown" и соответствующего тега <link> в <head>. Это позволяет AI-агентам, которые ещё не поддерживают заголовок Accept: text/markdown, обнаружить Markdown-версию по ссылке.

Как работает конвертация

Плагин сначала рендерит Gutenberg-блоки, а затем преобразует результат в Markdown. Такой подход гарантирует, что динамические блоки, вставки (embeds) и таблицы передаются корректно. Дополнительно удаляется обёртка синтаксических подсветок (Prism, highlight.js и подобные), чтобы в коде не оставалось шума из <span class="token …">.

Для производительности реализовано кеширование на уровне объектного кеша (Redis/Memcached). Ключ формируется на основе хеша контента, поэтому повторные запросы пропускают этапы рендеринга блоков, раскрытия шорткодов и конвертации HTML → Markdown.

Поддержка фидов

Плагин добавляет Markdown-представление и для лент:

/feed/markdown/ — выделенный Markdown-фид с метаданными сайта, заголовками, авторами, датами, категориями, метками и полным содержимым постов;
/feed/ с заголовком Accept: text/markdown возвращает основной фид в Markdown;
/post-slug/feed/ с тем же заголовком отдаёт пост вместе со всеми комментариями.

Markdown-фид также анонсируется в RSS через <atom:link rel="alternate" type="text/markdown">, что позволяет ридерам и AI-агентам находить его автоматически.

Гибкая настройка через фильтры

Плагин предоставляет несколько фильтров для адаптации под конкретные нужды:

post_content_to_markdown/post_types — включение страниц и произвольных типов записей (по умолчанию только post);
post_content_to_markdown/post_allowed — разрешающий список на уровне отдельной записи;
post_content_to_markdown/converter_options — управление стилем заголовков, жёсткими переносами и удаляемыми узлами;
post_content_to_markdown/conversion_cache_duration — изменение TTL кеша для блоков, чувствительных к запросу;
post_content_to_markdown/markdown_output — финальная обработка сконвертированного Markdown, выполняемая при каждом запросе вне кеша, что позволяет вносить правки без инвалидации кеша.

Полный список фильтров доступен в документации репозитория.

Стандарты и безопасность

В отличие от многих аналогов, плагин строго следует RFC 9110 §12.5.1 по упреждающему согласованию контента:

корректно обрабатывает q-значения, поэтому заголовок Accept: text/html;q=0.9, text/markdown;q=1.0 правильно предпочитает Markdown;
на каждый фронтенд-ответ добавляется Vary: Accept, чтобы браузеры, прокси и CDN не перемешивали HTML и Markdown для разных клиентов;
если клиентский Accept исключает все доступные представления, возвращается 406 Not Acceptable, а не молчаливый фолбек на HTML;
в ответах с Markdown проставляется заголовок X-Markdown-Source: accept | md-url | query, позволяя отслеживать в логах, как именно клиент запросил контент;
ответы на .md URL содержат X-Robots-Tag: noindex, nofollow, чтобы поисковые системы не индексировали Markdown-дубликат рядом с канонической HTML-страницей.

Результат

После активации плагина сайт на WordPress сразу получает полноценную поддержку Markdown для AI-агентов без необходимости создавать дополнительные REST-маршруты или менять структуру контента. AI-инструменты, поддерживающие заголовок Accept: text/markdown, начинают получать чистый контент, а те, что ещё не поддерживают, могут перейти по альтернативной ссылке. Владельцы сайтов получают прозрачный механизм согласования, кеширования и контроля через фильтры, а также инструменты для проверки готовности сайта к AI через сервис acceptmarkdown.com.

Качественные изменения включают:

снижение объёма передаваемых данных за счёт удаления HTML-обёртки;
корректную обработку динамических блоков Gutenberg;
соблюдение HTTP-стандартов, что исключает проблемы с кешированием и совместимостью;
возможность мониторинга использования Markdown-версий через access-логи.

Плагин устанавливается через Composer (composer require roots/post-content-to-markdown) и не требует сложной настройки — существующие посты сразу получают Markdown-представление. Исходный код открыт на GitHub, принимаются issues и pull-реквесты.