For AI agents: the complete documentation index is available at /rspress-russian/llms.txt, the full documentation bundle is available at /rspress-russian/llms-full.txt, and this page is available as Markdown at /rspress-russian/blog/agent-friendly-website.md.
close

20 августа 2026 года

Как создать сайт, удобный для агентов

Такие агенты, как Claude Code, Cursor и Codex, уже ищут документацию, вызывают API и непосредственно пишут код. Люди больше не являются единственными читателями документации инструментов для разработчиков.

Однако сайт, обеспечивающий отличное взаимодействие для людей, всё ещё может быть неудобен для агентов:

  • Люди могут перемещаться по навигации, тогда как агенты могут не знать, с чего начать;
  • Люди видят полностью отрендеренную страницу, тогда как агенты могут получить лишь пустую оболочку, ожидающую выполнения JavaScript;
  • Люди могут не обращать внимания на навигацию, кнопки и рекламу, тогда как агентам необходимо извлекать основное содержимое из большого объёма HTML;
  • Даже если сайт предоставляет Markdown, агенты могут не знать о его существовании.

Rspress — генератор статических сайтов на основе Rsbuild. Его цель — сделать каждый документ удобнее для обнаружения, чтения и понимания агентами. В этой статье представлены лучшие практики Rspress по созданию сайтов, удобных для агентов.

Rspress набирает 100/100 баллов в AFDocs

llms.txt: Карта сайта для эпохи агентов

Спецификация llms.txt определяет Markdown-индекс, размещаемый в корне сайта или в его подкаталоге. Он содержит введение в сайт и ссылки на подробный контент.

sitemap.xml помогает поисковым системам индексировать страницы, а llms.txt помогает агентам обнаруживать содержимое с помощью поэтапного раскрытия информации: сначала он предоставляет краткий индекс документации, а затем позволяет агентам по запросу читать релевантные страницы.

Например, файл llms.txt сайта Rspress доступен по адресу https://rspress.rs/llms.txt:

# Rspress

> Rspress — генератор статических сайтов на основе Rspack.

## Документация

- [Введение](https://rspress.rs/guide/start/introduction.md): Введение в Rspress
- [Быстрый старт](https://rspress.rs/guide/start/quick-start.md): Быстрый старт
// ...

Текущий результат doc_build в Rspress делится на три категории: HTML для людей, Markdown для каждой страницы для агентов и индексные файлы для обнаружения содержимого.

doc_build/
├── index.html                              # HTML-страница для людей
├── index.md                                # Markdown-страница для агентов
├── guide/
│   └── start/
│       ├── introduction.html               # HTML-страница для людей
│       └── introduction.md                 # Markdown-страница для агентов
├── sitemap.xml                             # Индекс HTML-документации
├── llms.txt                                # Краткий индекс в формате Markdown
└── llms-full.txt                           # Markdown-содержимое всего сайта

SSG-MD: Версия SSG в формате Markdown

Rspress предоставляет генерацию статических сайтов в Markdown (SSG-MD). Подобно генерации статических сайтов (SSG), SSG-MD преобразует страницы в файлы Markdown вместо HTML-файлов, а также создаёт llms.txt и llms-full.txt, благодаря чему техническую документацию становится проще понимать и использовать большим языковым моделям.

Rspress — это не только фреймворк для SSG: благодаря SSG-MD он также рассматривает генерацию Markdown как полноценную возможность: HTML для людей, Markdown для ИИ.

В следующей таблице сравниваются SSG и SSG-MD:

СравнениеSSGSSG-MD
Полное названиеStatic Site GenerationStatic Site Generation to Markdown
Цель оптимизацииSEO (поисковая оптимизация)GEO (оптимизация для генеративных систем)
Целевой потребительПоисковый роботLLM / система векторного поиска
Индексный файлsitemap.xmlllms.txt
Файл с полным содержимым-llms-full.txt
Ключевая реализацияrenderToStringrenderToMarkdownString
Способ доступа/guide/start/introduction.html/guide/start/introduction.md

Почему SSG-MD?

Во фронтенд-фреймворках на основе React извлечение статической информации из динамически отрендеренного содержимого зачастую затруднено. MDX сталкивается с той же проблемой: файлы .mdx содержат Markdown, но также могут включать React-компоненты, делая документацию более интерактивной. Rspress позволяет пользователям расширять документацию с помощью фрагментов MDX, React-компонентов, хуков и маршрутов TSX, однако этот динамический контент создаёт проблемы при преобразовании в Markdown:

  • Передача исходного MDX в ИИ добавляет шум в виде синтаксиса кода и приводит к потере содержимого отрендеренных React-компонентов.

  • Преобразование HTML в Markdown часто даёт неудовлетворительные результаты, из-за чего сложно гарантировать качество информации.

Генерация статических сайтов (SSG) создаёт статический HTML для поисковых роботов и улучшает SEO. SSG-MD решает аналогичную проблему для инструментов ИИ: он улучшает GEO и качество статической информации для больших языковых моделей. В отличие от преобразования HTML в Markdown, рендеринг из виртуального DOM React предоставляет SSG-MD более богатый источник информации.

Схема работы SSG-MD

Как работает SSG-MD?

  1. Внутри Rspress реализован метод renderToMarkdownString, аналогичный renderToString из react-dom, который преобразует React-компоненты в строки Markdown:
import { renderToMarkdownString } from 'react-render-to-markdown';

// HTML-элементы преобразуются в соответствующий синтаксис Markdown
renderToMarkdownString(
  <div>
    <strong>foo</strong>
    <span>bar</span>
  </div>,
);
// Результат: '**foo**bar'

// Поддерживаются React-компоненты и хуки
const Article = () => {
  return (
    <>
      <h1>Привет, мир</h1>
      <p>Это параграф.</p>
    </>
  );
};
renderToMarkdownString(<Article />);
// Результат: '# Привет, мир\n\nЭто параграф.\n'

В принципе, этот API работает с любым сайтом, созданным с использованием React; если вам это интересно, см. react-render-to-markdown.

  1. Rspress использует собственный плагин remark remarkSplitMdx для предварительной обработки MDX-файлов перед рендерингом. Этот плагин разделяет AST MDX, отделяя обычное содержимое Markdown от JSX-компонентов: текст Markdown сериализуется в строковые литералы, а JSX-компоненты и MDX-выражения (например, {variable}) сохраняются как React-элементы. Это позволяет передавать содержимое Markdown как есть, не обрабатывая его через React-рендеринг, в то время как динамические компоненты рендерятся с помощью renderToMarkdownString.

Например, следующий MDX:

# Привет

Немного **жирного** текста.

<PackageManagerTabs command="install rspress" />

{window.title}

преобразуется в компонент следующего вида:

function _createMdxContent() {
  return (
    <>
      {'# Привет\n\nНемного **жирного** текста.\n'}
      <PackageManagerTabs command="install rspress" />
      {window.title}
    </>
  );
}
  1. Rspress предоставляет переменную окружения import.meta.env.SSG_MD, благодаря которой React-компоненты могут отличать рендеринг SSG-MD от рендеринга в браузере и соответствующим образом настраивать свой вывод:
export function Tab({ label }: { label: string }) {
  if (import.meta.env.SSG_MD) {
    return <>{`**Вот вкладка под названием ${label}**`}</>;
  }
  return <div>{label}</div>;
}
  1. Внутренняя библиотека компонентов Rspress адаптирована для SSG-MD, поэтому на этапе SSG-MD компоненты генерируют содержательный Markdown. Например:
<PackageManagerTabs command="create rspress@latest" />

Он преобразуется в:

```sh [npm]
npm create rspress@latest
```

```sh [yarn]
yarn create rspress
```

```sh [pnpm]
pnpm create rspress@latest
```

```sh [bun]
bun create rspress@latest
```

```sh [deno]
deno init --npm rspress@latest
```

Accept: text/markdown: Возвращение Markdown на основе заголовка запроса

В ноябре 2025 года Boris Cherny, руководитель Claude Code, написал в X:

В следующей версии Claude Code инструмент WebFetch будет автоматически добавлять к запросам Accept: "text/markdown, *", что поможет сайтам с документацией предоставлять документацию, требующую меньше токенов.

Cloudflare также отмечает, что такие агенты для работы с кодом, как Claude Code и OpenCode, отправляют заголовок запроса Accept, содержащий text/markdown.

Клиенты для агентов, такие как Claude Code, и сайты с документацией, такие как Bun, одними из первых начали использовать соглашение Accept: text/markdown. По сравнению с HTML Markdown не содержит элементы оформления страницы, такие как навигация, стили и скрипты, требует меньше контекста и избавляет от необходимости извлекать основное содержимое из HTML. Поэтому агенты могут быстрее получать пригодный для использования контент. Если сайт уже генерирует Markdown, поддержка этого заголовка делает эти преимущества надёжными, вместо того чтобы полагаться на самостоятельный разбор HTML каждым клиентом.

Rspress — полностью статический фреймворк и не имеет сервера развёртывания, который выбирал бы HTML или Markdown в зависимости от заголовка запроса. Тем не менее поддержать этот заголовок достаточно просто: нужно настроить соответствующее правило у провайдера хостинга. На сайте Rspress используется перенаправление Cloudflare. Запросы, содержащие Accept: text/markdown, внутренне перенаправляются на соответствующий .md-файл по тому же пути, тогда как обычные браузеры по тому же URL по-прежнему получают HTML.

curl https://rspress.rs/guide/start/introduction \
  -H 'Accept: text/markdown'

Ответ представлен в формате Markdown:

> For AI agents: the complete documentation index is available at
> https://rspress.rs/llms.txt ...

# Введение

Rspress — генератор статических сайтов на основе React, созданный на базе Rsbuild.

AFDocs: Проверки и оценка

AFDocs — сопутствующий инструмент с открытым исходным кодом для спецификации документации, удобной для ИИ-агентов. В справочнике проверок перечислены 23 проверки в 7 категориях, а также критерии прохождения, предупреждения и ошибки для каждой проверки.

Несколько описанных в этой статье оптимизаций Rspress для агентов можно проверить с помощью AFDocs:

Возможность RspressПроверки AFDocsЧто проверяется
llms.txtllms-txt-exists, llms-txt-validМогут ли агенты найти и разобрать индекс документации
SSG-MDmarkdown-url-supportПредоставляется ли для каждой страницы версия в Markdown
Accept: text/markdowncontent-negotiationВозвращается ли Markdown в ответ на соответствующий заголовок запроса
LlmsHintllms-txt-directive-html, llms-txt-directive-mdМогут ли агенты обнаружить индекс с одной страницы
Двойной выводmarkdown-content-parityВыражают ли HTML и Markdown одно и то же содержимое

Rspress также использует другие проверки AFDocs для дальнейшего улучшения, включая такие метрики, как размер HTML.

Выполните следующую команду, чтобы проверить общедоступный сайт с документацией:

npx afdocs check https://docs.example.com --format scorecard

Отчёт содержит результат каждой проверки, рекомендуемые изменения и итоговую оценку, что делает его полезным для сравнения сайта до и после обновления с учётом требований агентов.

Agent Score от Mintlify также основан на этой спецификации. Помимо 23 базовых проверок, он добавляет проверки обнаруживаемости полного содержимого, Agent Skills и MCP-серверов.

Важно отметить, что AFDocs не оценивает качество написания документации или правильность ответов агентов. Он лишь проверяет набор верифицируемых правил.

injectLlmsHint: Предоставление URL llms.txt

Проверки обнаруживаемости содержимого AFDocs включают два релевантных правила:

  • llms-txt-directive-html: Если агент напрямую открывает HTML-страницу, может ли он узнать, что на сайте есть llms.txt и Markdown-версия текущей страницы?
  • llms-txt-directive-md: Если агент получает Markdown-страницу, может ли он узнать, где находится вся документация сайта?

Даже если сайт предоставляет Markdown, агент, попавший на глубоко вложенную страницу, может не знать, что для текущей страницы существует Markdown-версия или что существует /llms.txt. Поэтому каждая страница должна явно предоставлять эти точки входа.

Rspress включает injectLlmsHint по умолчанию. Когда включён SSG-MD, Rspress вставляет визуально скрытый обычный текст в начало основного содержимого сгенерированного HTML:

<div class="rp-llms-hint" style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);clip-path:inset(50%);white-space:nowrap;border:0">For AI agents: the complete documentation index is available at https://example.com/llms.txt, the full documentation bundle is available at https://example.com/llms-full.txt, and this page is available as Markdown at https://example.com/guide/index.md.</div>

Здесь не используются display: none, hidden или aria-hidden. URL также отображаются непосредственно в виде обычного текста, а не заключены в элементы ссылок. Подсказка остаётся невидимой для читателей, но сохраняется в DOM, благодаря чему агенты, которые разбирают HTML или преобразуют HTML в Markdown, могут сохранить и прочитать эту директиву.

Правило llms-txt-directive-html в AFDocs предъявляет то же требование: директиву можно визуально скрыть с помощью таких методов, как clip-rect или sr-only, но она должна оставаться в DOM и сохраняться при преобразовании HTML в Markdown.

Сгенерированный Markdown-вывод также включает следующее содержимое:

> For AI agents: the complete documentation index is available at
> https://example.com/llms.txt, the full documentation bundle is available at
> https://example.com/llms-full.txt.

Этим двум выводам соответствуют проверки llms-txt-directive-html и llms-txt-directive-md.

Ссылки