#@rspress/plugin-llms

Исходный код

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

#Установка

npm add @rspress/plugin-llms -D

yarn add @rspress/plugin-llms -D

pnpm add @rspress/plugin-llms -D

bun add @rspress/plugin-llms -D

deno add npm:@rspress/plugin-llms -D

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

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

Добавьте следующую конфигурацию:

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

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

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

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

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

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

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

import { defineConfig } from '@rspress/core';
import { pluginLlms } from '@rspress/plugin-llms';

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

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

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

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

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} />
        <LlmsContainer>
          <LlmsCopyButton />
          {/* Добавьте LlmsViewOptions, если нужно */}
          <LlmsViewOptions />
        </LlmsContainer>
      </>
    );
  };
  return {
    ...mdxComponents,
    h1: MyH1,
  };
}

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

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

# Привет, мир

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

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

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

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

• Тип:

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;
}

• По умолчанию:

Если интернационализация не включена, значение по умолчанию:

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

Если интернационализация включена, будет использоваться групповая конфигурация, а значение по умолчанию:

[
  {
    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

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 по умолчанию выглядит так:

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

Например:

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

> ${description}

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

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

# Rspress - llms.txt

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

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

## guide

- [foo](/foo.md)

#mdFiles

• Тип: false | MdFiles

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

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 и связанные файлы только для страниц на английском языке:

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

#exclude

• Тип: (context: { page: PageIndexInfo }) => boolean

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

• Пример:

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

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

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

#LlmsCopyButtonProps

• Тип: LlmsCopyButtonProps

interface LlmsCopyButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {}

#LlmsViewOptionsProps

• Тип: LlmsViewOptionsProps

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[]

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

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

Настраивает параметры в выпадающем меню. По умолчанию поддерживаются «Скопировать ссылку Markdown», ChatGPT и Claude.

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

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

• Пример：

// rspress.config.ts
import { defineConfig } from '@rspress/core';
defineConfig({
  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',
      },
    ]),
  ],
});