> 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.

# @rspress/plugin-llms 

[Исходный код](https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-llms)

Генерируйте связанные с [llms.txt](https://llmstxt.org/) файлы для вашего сайта Rspress, чтобы большие языковые модели могли лучше понимать вашу документацию.

:::warning

`@rspress/plugin-llms` использует remark для обработки исходных файлов MDX, поэтому он не поддерживает рендеринг динамического контента, такого как React Hooks или пользовательские компоненты.

Этот плагин предназначен только как запасной вариант, когда SSG и SSG-MD нельзя включить из-за несовместимости кода с SSR. Предпочтительнее использовать функцию [SSG-MD](/rspress-russian/guide/basic/ssg-md.md), когда это возможно.

:::

## Установка


```sh [npm]
npm add @rspress/plugin-llms -D
```

```sh [yarn]
yarn add @rspress/plugin-llms -D
```

```sh [pnpm]
pnpm add @rspress/plugin-llms -D
```

```sh [bun]
bun add @rspress/plugin-llms -D
```

```sh [deno]
deno add npm:@rspress/plugin-llms -D
```

## Использование

### 1. Подключение плагина

Установите `llms: false`, чтобы отключить встроенную генерацию SSG-MD при использовании этого плагина:

```ts
// rspress.config.ts
import { defineConfig } from '@rspress/core';
import { pluginLlms } from '@rspress/plugin-llms';

export default defineConfig({
  llms: false,
  plugins: [pluginLlms()],
});
```

Затем выполните команду `rspress build`. Во время генерации сборки плагин дополнительно создаст в выходной директории файлы `llms.txt`, `llms-full.txt`, а также отдельные markdown-файлы для каждого маршрута на основе структуры навигации и бокового меню.

### 2. Отображение в интерфейсе

Чтобы помочь читателям использовать вашу документацию с большими языковыми моделями, добавьте кнопку копирования Markdown в верхней части страницы, как на этом сайте.

#### Использование themeConfig (рекомендуемый способ)

Самый простой способ — включить `llmsUI` в `themeConfig`. Это автоматически добавит компоненты `LlmsCopyButton` и `LlmsViewOptions` под всеми заголовками H1 (или в панели оглавления) без необходимости писать код пользовательской темы:

```ts title="rspress.config.ts"
import { defineConfig } from '@rspress/core';
import { pluginLlms } from '@rspress/plugin-llms';

export default defineConfig({
  llms: false,
  plugins: [pluginLlms()],
  themeConfig: {
    llmsUI: true,
    // Или с пользовательскими настройками:
    // llmsUI: {
    //   injectLlmsHint: false, // Отключить подсказку с директивой для LLM в HTML/Markdown
    //   viewOptions: ['markdownLink', 'chatgpt', 'claude'],
    //   placement: 'outline', // Отображать в панели оглавления вместо размещения под заголовком H1
    // },
  },
});
```

#### Использование своей темы

Если вам нужен больший контроль, вы можете использовать [кастомную тему](/rspress-russian/guide/basic/custom-theme.md), чтобы добавить кнопку копирования Markdown.

Пример добавления кнопки копирования на все страницы:

```tsx title="theme/index.tsx"
import { getCustomMDXComponent as basicGetCustomMDXComponent } from '@rspress/core/theme';
import {
  LlmsContainer,
  LlmsCopyButton,
  LlmsViewOptions,
} from '@rspress/plugin-llms/runtime';

function getCustomMDXComponent() {
  const { h1: H1, ...mdxComponents } = basicGetCustomMDXComponent();

  const MyH1 = ({ ...props }) => {
    return (
      <>
        <H1 {...props} />
        {/* [!code highlight:5] */}
        <LlmsContainer>
          <LlmsCopyButton />
          {/* Добавьте LlmsViewOptions, если нужно */}
          <LlmsViewOptions />
        </LlmsContainer>
      </>
    );
  };
  return {
    ...mdxComponents,
    h1: MyH1,
  };
}

export { getCustomMDXComponent };
export * from '@rspress/core/theme-original';
```

Добавляем кнопку копирования на отдельные страницы:

```mdx title="docs/hello-world.mdx"
# Привет, мир

<LlmsContainer>
  <LlmsCopyButton />
  <LlmsViewOptions /> {/* Добавьте LlmsViewOptions, если нужно */}
</LlmsContainer>

Пример документа
```

## Конфигурация

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

- **Тип**:


```ts
interface LlmsTxt {
  name: string;
  onTitleGenerate?: (context: {
    title: string | undefined;
    description: string | undefined;
  }) => string;
  onLineGenerate?: (page: PageIndexInfo) => string;
  onAfterLlmsTxtGenerate?: (llmsTxtContent: string) => string;
}

interface MdFiles {
  mdxToMd?: boolean;
  remarkPlugins?: PluggableList;
}

interface LlmsFullTxt {
  name: string;
}

export interface Options {
  llmsTxt?: false | LlmsTxt;
  mdFiles?: false | MdFiles;
  llmsFullTxt?: false | LlmsFullTxt;
  include?: (context: { page: PageIndexInfo }) => boolean;
  exclude?: (context: { page: PageIndexInfo }) => boolean;
}
```

- **По умолчанию**:

Если [интернационализация](/rspress-russian/guide/basic/i18n.md) не включена, значение по умолчанию:

```ts
{
  llmsTxt: { name: 'llms.txt' },
  llmsFullTxt: { name: 'llms-full.txt' },
  mdFiles: true
}
```

Если [интернационализация](/rspress-russian/guide/basic/i18n.md) включена, будет использоваться [групповая конфигурация](#group), а значение по умолчанию:

```ts
[
  {
    llmsTxt: { name: 'llms.txt' },
    llmsFullTxt: { name: 'llms-full.txt' },
    mdFiles: true,
    include: ({ page }) => page.lang === config.lang,
  },
  // Автоматически генерируем файлы для остальных языков на основе конфигурации locales
  {
    llmsTxt: { name: `${lang}/llms.txt` },
    llmsFullTxt: { name: `${lang}/llms-full.txt` },
    mdFiles: true,
    include: ({ page }) => page.lang === lang,
  },
  // ...
];
```

### llmsTxt

- **Тип**: `false | LlmsTxt`

```ts
import type { PageIndexInfo } from '@rspress/core';

export interface LlmsTxt {
  name: string;
  onTitleGenerate?: (context: {
    title: string | undefined;
    description: string | undefined;
  }) => string;
  onLineGenerate?: (page: PageIndexInfo) => string;
  onAfterLlmsTxtGenerate?: (llmsTxtContent: string) => string;
}
```

- **Значение по умолчанию**: `{ name: 'llms.txt' }`

Управляет тем, будет ли генерироваться файл `llms.txt`, либо позволяет настроить его через хуки.

Формат файла `llms.txt` по умолчанию выглядит так:

```markdown
# {title}

> {description}

## {nav1.title}

- [{page.title}]({ page.routePath }): {page.frontmatter.description}

## {nav2.title}

- [{page.title}]({ page.routePath }): {page.frontmatter.description}
```

Вы можете изменить отдельные части через хуки:

- `onTitleGenerate`: Настраивает заголовок и секцию описания.
- `onLineGenerate`: Настраивает каждую строку Markdown-файла.
- `onAfterLlmsTxtGenerate`: Позволяет изменить итоговое содержимое файла `llms.txt`.

Например:

```ts
pluginLlms({
  llmsTxt: {
    onTitleGenerate: ({ title, description }) => {
      return `# ${title} - llms.txt

> ${description}

Rspress — это статический генератор сайтов на основе Rsbuild, который умеет генерировать llms.txt с помощью плагина `@rspress/plugin-llms`.
`;
    },
  },
});
```

Сгенерированный результат:

```markdown
# Rspress - llms.txt

> Статический генератор сайтов на базе Rsbuild

Rspress — это статический генератор сайтов на основе Rsbuild, который умеет генерировать llms.txt с помощью плагина `@rspress/plugin-llms`.

## guide

- [foo](/foo.md)
```

### mdFiles

- **Тип**: `false | MdFiles`

```ts
export interface MdFiles {
  mdxToMd?: boolean;
  remarkPlugins?: PluggableList;
}
```

- **Значение по умолчанию**: `{ mdxToMd: false, remarkPlugins: [] }`

Управляет тем, будет ли генерироваться Markdown-файл для соответствующего маршрута. Если установлено значение `false`, Markdown-файл для этого маршрута не создаётся.

#### mdxToMd

- **Тип**: `boolean`
- **Значение по умолчанию**: `false`

Управляет тем, будет ли MDX-контент преобразовываться в Markdown. Если включено, MDX-файлы конвертируются в Markdown с использованием набора стандартных стратегий, однако часть информации может быть потеряна.

#### remarkPlugins

- **Тип**: `PluggableList`
- **Значение по умолчанию**: `[]`

Вы можете передать свои remark-плагины для изменения содержимого Markdown.

### llmsFullTxt

- **Тип**: `false | LlmsFullTxt`

```ts
export interface LlmsFullTxt {
  name: string;
}
```

- **Значение по умолчанию**: `{ name: 'llms-full.txt' }`

Управляет тем, будет ли генерироваться файл `llms-full.txt`. Если установлено значение `false`, файл `llms-full.txt` не создаётся.

### include

- **Тип**: `(context: { page: PageIndexInfo }) => boolean`

Определяет, какие страницы включаются в процесс генерации. Обычно используется для упрощения файла `llms.txt`.

- Пример:

Генерировать `llms.txt` и связанные файлы только для страниц на английском языке:

```ts
pluginLlms({
  llmsTxt: {
    name: 'llms.txt',
  },
  llmsFullTxt: {
    name: 'llms-full.txt',
  },
  include: ({ page }) => {
    return page.lang === 'en';
  },
});
```

### exclude

- **Тип**: `(context: { page: PageIndexInfo }) => boolean`

Определяет, какие страницы исключаются из генерации. Выполняется после применения `include`.

- Пример:

Исключить одну страницу внутри маршрута `/foo`:

```ts
pluginLlms({
  llmsTxt: {
    name: 'llms.txt',
  },
  llmsFullTxt: {
    name: 'llms-full.txt',
  },
  exclude: ({ page }) => {
    return page.routePath === '/foo';
  },
});
```

## Пропсы UI-компонента

### LlmsCopyButtonProps

- **Тип**: `LlmsCopyButtonProps`

```ts
interface LlmsCopyButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {}
```

### LlmsViewOptionsProps

- **Тип**: `LlmsViewOptionsProps`

```ts
type LlmsViewOptionsItem =
  | {
      title: string;
      icon?: React.ReactNode;
      onClick?: () => void;
    }
  | {
      title: string;
      href: string;
      icon?: React.ReactNode;
    }
  | 'markdownLink'
  | 'chatgpt'
  | 'claude';

interface LlmsViewOptionsProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  options?: LlmsViewOptionsItem[];
}
```

#### options

- **Тип**: `LlmsViewOptionsItem[]`

```ts
type LlmsViewOptionsItem =
  | {
      title: string;
      icon?: React.ReactNode;
      onClick?: () => void;
    }
  | {
      title: string;
      href: string;
      icon?: React.ReactNode;
    }
  | 'markdownLink'
  | 'chatgpt'
  | 'claude';
```

- **Значение по умолчанию**: `['markdownLink', 'chatgpt', 'claude']`

Настраивает параметры в выпадающем меню. По умолчанию поддерживаются «Скопировать ссылку Markdown», [ChatGPT](https://chatgpt.com/) и [Claude](https://claude.ai).

## Одновременная генерация нескольких групп `llms.txt` \{#group}

В некоторых случаях, например для многоязычных (i18n) сайтов, может потребоваться генерировать несколько групп `llms.txt`. Для этого передаётся массив.

- Пример：

```ts
// rspress.config.ts
import { defineConfig } from '@rspress/core';
defineConfig({
  llms: false,
  lang: 'en',
  plugins: [
    pluginLlms([
      {
        llmsTxt: {
          name: 'llms.txt',
        },
        llmsFullTxt: {
          name: 'llms-full.txt',
        },
        include: ({ page }) => page.lang === 'en',
      },
      {
        llmsTxt: {
          name: 'ru/llms.txt',
        },
        llmsFullTxt: {
          name: 'ru/llms-full.txt',
        },
        include: ({ page }) => page.lang === 'ru',
      },
    ]),
  ],
});
```
