Перейти к содержимому
LLMs Full Text
Выберите тему

Markdown-версии страниц

Зачем сайту Markdown-версии страниц для AI-агентов, три способа их отдавать - отдельный адрес .md, заголовок Accept и ссылка rel=alternate - и что об их пользе известно на самом деле

HTML и Markdown одной страницы

Заголовок раздела «HTML и Markdown одной страницы»
Что получает клиент

HTML

для браузера и поиска

  • Меню, шапка, подвал, скрипты, стили
  • Структурированные данные в коде страницы
  • Много служебной разметки вокруг текста

Markdown

для агента

  • Только содержание
  • Заголовки и списки сохраняют структуру
  • Нет JSON-LD и интерактивных частей

Три способа отдать Markdown

Заголовок раздела «Три способа отдать Markdown»

К адресу страницы добавляется .md. Способ описан во второй редакции proposal llms.txt.

https://example.ru/docs/install.html      страница
https://example.ru/docs/install.html.md   её Markdown-версия


https://example.ru/docs/                  страница без имени файла
https://example.ru/docs/index.html.md     её Markdown-версия

Допустимы обе формы: page.html.md и page.md. Плюс способа: адрес можно открыть в браузере и положить в llms.txt.

Способы не исключают друг друга. Подробно о связях обнаружения: Обнаружение файла и Markdown-версий.

Что должно быть в Markdown-версии

Заголовок раздела «Что должно быть в Markdown-версии»
  • То же содержание, что в HTML. Другой текст для машины - это подмена, и поисковые системы относятся к ней плохо.
  • Один заголовок первого уровня и осмысленные заголовки разделов.
  • Абсолютные ссылки. Агент читает файл вне сайта, относительный путь ему некуда приложить.
  • Таблицы таблицами, код в блоках кода. Снимок экрана с таблицей машина не прочитает.
  • Без навигации, подвала и форм.
  • Тип ответа text/markdown или text/plain, кодировка UTF-8.

Связь с llms.txt

Заголовок раздела «Связь с llms.txt»

В llms.txt лучше ссылаться на Markdown-версии, если они есть. Тогда агент проходит путь целиком: карта, затем чистый текст.

Если Markdown-версий нет, файл со ссылками на обычные страницы всё равно корректен. Proposal рекомендует Markdown, но не требует.

Что известно о пользе

Заголовок раздела «Что известно о пользе»

Что известно, а что нет

Подтверждено

  • Сайты документации OpenAI, Anthropic, Stripe, Cloudflare, GitHub отдают Markdown-версии страниц.
  • Платформы документации создают их автоматически для всех сайтов.
  • Mintlify сообщает, что на её сайтах агенты запрашивают документацию чаще людей. Источник заинтересован: это его продукт.

Не доказано

  • Что Markdown-версия увеличивает число цитирований или переходов.
  • Что боты поисковых AI-систем сами запрашивают .md. В опыте OtterlyAI за 14 дней таких обращений не было ни одного.

Чего это не означает

  • Это не способ попасть в поисковый индекс: поиск читает HTML.
  • Это не замена структурированным данным: в Markdown нет разметки сущностей.

Markdown-версии публикуют крупные сайты документации. Независимых замеров пользы пока мало.

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

Подробнее в блоге: Cloudflare отдаёт агентам Markdown, опыт Mintlify с четырьмя форматами.

Как проверить

Заголовок раздела «Как проверить»
  1. Запроси страницу с заголовком Accept: text/markdown или открой адрес с .md.
  2. Ответ 200, тип text/markdown или text/plain.
  3. В ответе текст, а не HTML-страница.
  4. Содержание совпадает с обычной страницей.
  5. Ссылки абсолютные и рабочие.
  6. Если есть rel="alternate", адрес в нём отвечает 200.
Окно терминала
curl -sI -H 'Accept: text/markdown' https://example.ru/docs/install/
curl -sI https://example.ru/docs/install.html.md

Кто так делает

Заголовок раздела «Кто так делает»

  • OpenAI

    developers.openai.com/llms.txt
    llms-full.txt
    есть
    Markdown-страницы
    по заголовку Accept

    Что показывает. Корневой индекс и вложенные файлы для /api, /codex, /commerce

    Чего не доказывает. Что ChatGPT читает чужие llms.txt

  • Anthropic

    platform.claude.com/llms.txt
    llms-full.txt
    есть
    Markdown-страницы
    да, с rel=alternate

    Что показывает. Индекс документации и полный текст одним файлом

    Чего не доказывает. Что Claude читает чужие llms.txt

  • Cloudflare

    developers.cloudflare.com/llms.txt
    llms-full.txt
    есть
    Markdown-страницы
    да

    Что показывает. Очень большой индекс: полный текст занимает 67 МБ

    Чего не доказывает. Что файл такого размера удобен агенту целиком

  • Stripe

    docs.stripe.com/llms.txt
    llms-full.txt
    нет
    Markdown-страницы
    по заголовку Accept

    Что показывает. llms-full.txt не обязателен: хватает индекса и Markdown-страниц

    Чего не доказывает. Что отказ от полного файла - общее правило

  • Cursor

    cursor.com/llms.txt
    llms-full.txt
    не проверялось
    Markdown-страницы
    по заголовку Accept

    Что показывает. Единственный замеренный сайт с rel=describedby из второй редакции

    Чего не доказывает. Что вторая редакция уже распространена

  • GitHub Docs

    docs.github.com/llms.txt
    llms-full.txt
    нет
    Markdown-страницы
    да

    Что показывает. Индекс без полного файла на большой документации

    Чего не доказывает. Что Copilot опирается на этот файл