Почему Markdown лучше HTML для AI-агентов
HTML-страница содержит навигацию, рекламные блоки, footer, счётчики и десятки служебных элементов, не относящихся к основному контенту. Агент вынужден «очищать» текст, теряя семантику в процессе. Markdown — это чистый текст с сохранённой структурой: заголовки, списки, таблицы, блоки кода с языком. Markdown-версия страницы обычно в 5–20 раз меньше HTML-версии по объёму. Исследователи Anthropic, документация Stripe и многие developer-платформы уже предоставляют .md-версии всех своих страниц именно по этой причине.
Три метода обнаружения Markdown
Инструмент проверяет все три стандартных способа. Метод 1 — .md суффикс: добавление .md к URL (/docs/page/ → /docs/page.md) возвращает Markdown с Content-Type: text/markdown. Метод 2 — Content Negotiation: запрос к основному URL с заголовком Accept: text/markdown — сервер отдаёт Markdown с заголовками Content-Location и Vary: Accept. Метод 3 — link rel="alternate": в HTML-заголовке присутствует <link rel="alternate" type="text/markdown" href="...">. Наличие хотя бы одного метода — уже хороший сигнал.
Как реализовать Markdown-эндпоинты
Для сайтов на основе статических генераторов (Hugo, Jekyll, Gatsby) предоставить .md файлы рядом с HTML — тривиальная задача: исходный файл уже существует. Для CMS (WordPress, 1С-Битрикс) потребуется плагин или middleware, конвертирующий контент в Markdown через html2md-библиотеку. Минимальный набор: корректный Content-Type, YAML frontmatter с title, URL и датой обновления. Дополнительно рекомендуется указывать оценку токенов в заголовке X-Markdown-Tokens — это помогает агентам управлять контекстным окном.
Типичные ошибки при реализации
Забытый Content-Type: text/markdown — браузер отдаёт файл как text/html, инструменты не распознают формат. При content negotiation обязателен заголовок Vary: Accept, иначе CDN закеширует HTML вместо Markdown. Критичная ошибка — вернуть нерасширенные шорткоды или template-синтаксис CMS: [gallery id="123"] бесполезен в Markdown. Несинхронизация HTML и Markdown версий (страница обновилась, .md нет) подрывает доверие к источнику. Если хотите предоставить весь контент сайта сразу — создайте /llms-full.txt как объединённый Markdown-документ.
