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

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

Генерация RSS-лент для выбранных страниц документации с помощью библиотеки [feed](https://github.com/jpmonette/feed).

## Установка


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

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

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

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

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

### Обновление конфигурации Rspress

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

export default defineConfig({
  plugins: [
    pluginRss({
      // URL вашего сайта с документацией
      siteUrl: 'https://example.com',
      // ...другие настройки
    }),
  ],
});
```

По умолчанию плагин генерирует файл `blog.xml` в папке `doc_build/rss/` для всех страниц, начинающихся с `/blog/`.

RSS-лента будет доступна по адресу `/rss/blog.xml`.

:::tip Подсказка
Плагин работает только при выполнении `rspress build` и **не** генерирует RSS-файлы в режиме `rspress dev`.
:::

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

### Выбор страниц, включаемых в RSS

Используйте опцию `feed.test`, чтобы указать, какие страницы должны попасть в RSS-ленту.

```ts
pluginRss({
  // ...
  feed: { test: '/zh/blog' },
});
```

### Требования

Все документы, включаемые в RSS, должны содержать в блоке метаданных поле `date` или `published_at`, чтобы обеспечить стабильные обновления RSS для читателей.

```md
---
published_at: 2024-01-10 08:00:00
---

Или значение мета-поля `date`.
```

### Генерация нескольких RSS-лент

Иногда требуется создать несколько RSS-файлов — например, для разных языков или категорий.

Передайте список параметров RSS в `feed`:

```ts
pluginRss({
  feed: [
    { id: 'blog', test: '/blog/', title: 'Rspress Blog', language: 'en-US' },
    {
      id: 'blog-ru',
      test: '/ru/blog/',
      title: 'Релизы Rspress',
      language: 'ru-RU',
    },
    {
      id: 'rspack',
      test: ({ frontmatter }) => frontmatter.categories.includes('rspack'),
      title: 'Rspack Releases',
      language: 'en-US',
    },
    {
      id: 'rsbuild',
      test: ({ frontmatter }) => frontmatter.categories.includes('rsbuild'),
      title: 'Rsbuild Releases',
      language: 'en-US',
    },
  ],
});
```

Приведённые выше настройки создадут четыре RSS-файла: `blog.xml`, `blog-ru.xml`, `rspack.xml`, `rsbuild.xml`, все они будут находиться в папке `rss`.

### Изменение пути вывода

Вы можете настроить путь вывода с помощью параметров `output` и `feed.output`.

См. подробности в разделе [FeedOutputOptions](#feedoutputoptions) ниже.

### Подключение RSS к страницам документации

По умолчанию этот плагин добавляет тег `<link rel="alternate">` на выбранные страницы, включённые в RSS. Этот тег указывает на URL RSS-файла, чтобы RSS-ридеры могли автоматически его обнаруживать.

Чтобы добавить этот тег на страницы, которые не входят в RSS (например, на главную страницу), добавьте в блок метаданных поле `link-rss` со значением ID ленты. Например:

```markdown
---
link-rss: blog
---

Такое мета-поле добавляет на страницу тег `<link rel="alternate">` и указывает в нём URL RSS-ленты `blog`.

При этом сама эта страница **не** будет включена в данную RSS-ленту.
```

`link-rss` также поддерживает вставку нескольких тегов `<link>` (для разных лент) на одной странице:

```markdown
---
link-rss:
  - blog
  - releases
---
```

### Настройка содержимого RSS

RSS-файл состоит из двух основных частей:

- базовая информация о ленте — `channel`;
- список статей — `item`.

Настроить каждую из этих частей можно так:

- `channel` полностью настраивается через параметр `feed`. Подробности — в разделе [Другие опции](#other-options) ниже.
- `item` полностью настраивается через параметр `feed.item`. Подробности — в разделе [item](#item) ниже.

## Опции

### PluginRssOptions

Опции плагина.

```ts
export interface PluginRssOptions {
  siteUrl?: string;
  feed?: Partial<FeedChannel> | FeedChannel[];
  output?: Omit<FeedOutputOptions, 'filename'>;
}
```

#### `siteUrl`

- **Тип**: `string`
- **По умолчанию**: [`siteOrigin`](/rspress-russian/api/config/config-basic.md#siteorigin) + [`base`](/rspress-russian/api/config/config-basic.md#base), либо `base`, если `siteOrigin` не задан

URL сайта, на котором размещена текущая документация. Используется при формировании RSS-файла.

RSS-ссылки используются вне контекста страниц документации, поэтому укажите абсолютный URL с протоколом и доменом, например `https://example.com/base/`. Если задан параметр `base`, значение `siteUrl` на уровне плагина должно включать путь `base`.

Если в Rspress настроены параметры [`siteOrigin`](/rspress-russian/api/config/config-basic.md#siteorigin) и [`base`](/rspress-russian/api/config/config-basic.md#base), параметр `siteUrl` на уровне плагина можно не указывать. Полный URL формируется в следующем порядке: `siteOrigin + base + routePath`. Если не заданы ни `siteUrl` на уровне плагина, ни `siteOrigin`, плагин использует в качестве резервного варианта значение `base`. Это сохраняет существующее поведение с относительными путями, но не позволяет генерировать абсолютные RSS-ссылки.

```ts
// rspress.config.ts
import path from 'path';
import { defineConfig } from '@rspress/core';
import { pluginRss } from '@rspress/plugin-rss';

export default defineConfig({
  siteOrigin: 'https://example.com',
  base: '/base/',
  plugins: [
    // По умолчанию `siteUrl` имеет значение `https://example.com/base/`
    pluginRss(),
  ],
});
```

#### `feed`

- **Тип**: `FeedChannel | FeedChannel[]`
- **По умолчанию**: `{ id: 'blog', test: '/blog/' }`

Конфигурация RSS. Передайте массив, чтобы сгенерировать несколько RSS-файлов.

Подробности — в разделе [FeedChannel](#feedchannel).

#### `output`

- **Тип**: `Omit<FeedOutputOptions, "filename">`
- **По умолчанию**: `{ dir: 'rss', type: 'atom' }`

Настройки вывода файлов. См. подробнее в разделе [FeedOutputOptions](#feedoutputoptions) ниже.

### FeedChannel

Опции отдельной RSS-ленты.

```ts
export interface FeedChannel extends Partial<FeedOptions> {
  id: string;
  test:
    RegExp | string | (RegExp | string)[] | ((item: PageIndexInfo) => boolean);
  item?: (
    item: FeedItem,
    page: PageIndexInfo,
    siteUrl: string,
  ) => FeedItem | PromiseLike<FeedItem>;
  output?: FeedOutputOptions;
}
```

#### `id`

- **Тип**: `string`
- **Обязательный параметр**

Идентификатор RSS-ленты, который должен быть уникальным среди всех RSS-настроек. Также используется как имя файла RSS по умолчанию (без расширения).

#### `test`

- **Тип**: `RegExp | string | (RegExp | string)[] | ((item: PageIndexInfo) => boolean)`
- **Обязательный параметр**

Выбирает документы, которые будут включены в RSS. Поддерживаемые значения:

- `RegExp`: регулярное выражение, которое сопоставляется с маршрутом документа.
- `string`: сопоставление по префиксу маршрута документа.
- `(item: PageIndexInfo) => boolean`: фильтрация страниц на основе данных страницы и метаданных. Это также рекомендуемый способ включения по префиксу маршрута с возможностью исключать отдельные страницы, например `/blog/`.

:::tip
`item.routePath` не включает путь `base`.
:::

Например, если вы хотите включить только страницы статей внутри `/blog/`, но исключить саму индексную страницу блога:

```ts
feed: {
  id: 'blog',
  test: (item) => {
    return (
      item.routePath.startsWith('/blog/') && item.routePath !== '/blog/'
    );
  },
}
```

#### `item`

- **Тип**: `(item: FeedItem, page: PageIndexInfo, siteUrl: string) => FeedItem | PromiseLike<FeedItem>`
- **По умолчанию**: <SourceCode href="https://github.com/web-infra-dev/rspress/blob/main/packages/plugin-rss/src/createFeed.ts" />

Формирует структурированные данные каждой статьи в RSS-ленте.

См. тип структурированных данных: 

[Исходный код](https://github.com/jpmonette/feed/blob/8ca7f3e4e8e421e2a2632bb9524385e86f30744c/src/typings/index.ts#L1-L25)

Плагин имеет встроенный генератор, который использует метаданные документа и данные страницы.

Например, поле `content` в RSS сначала использует `summary` из метаданных, а затем, если оно отсутствует, — содержимое документа.

Передайте функцию `item`, чтобы изменить сгенерированные данные, которые передаются в первом параметре.

Например, следующая конфигурация укорачивает содержимое статей в RSS:

```ts
const item: FeedChannel['item'] = item => ({
  ...item,
  content: item.content.slice(0, 1000),
});
```

#### `output`

- **Тип**: `FeedOutputOptions`
- **По умолчанию**: использует опцию `output` плагина

По сравнению с опцией `output` на уровне плагина, эта опция также включает `filename` для изменения имени выходного файла.

См. подробности в [FeedOutputOptions](#feedoutputoptions) ниже.

#### Другие опции \{#other-options}

`FeedChannel`
 также наследует `FeedOptions`
 из пакета feed. Параметры, не перечисленные здесь, смотрите в 

[Исходный код](https://github.com/jpmonette/feed/blob/8ca7f3e4e8e421e2a2632bb9524385e86f30744c/src/typings/index.ts#L48-L67)

.
### FeedOutputOptions

Параметры вывода RSS. Они доступны как на уровне плагина, так и на уровне `feed`, со следующим типом:

```ts
interface FeedOutputOptions {
  dir?: string;
  type?: 'atom' | 'rss' | 'json';
  filename?: string;
  publicPath?: string;
  sorting?: (left: FeedItem, right: FeedItem) => number;
  transform?: (
    content: string,
    context: {
      type: 'atom' | 'rss' | 'json';
      feed: Feed;
      channel: FeedChannel;
    },
  ) => string | PromiseLike<string>;
}
```

Пример:

```ts
pluginRss({
  // Применяется ко всем RSS-выводам
  output: {
    // Изменяем папку вывода RSS-файлов на 'feeds' (относительно `doc_build`)
    dir: 'feeds',
    // Выводим в формате RSS 2.0, по умолчанию будет расширение `.rss`
    type: 'rss',
  },
  feed: [
    {
      id: 'blog',
      test: '/blog/',
      title: 'My Blog',
      output: {
        type: 'atom' /* по умолчанию имя файла берётся из `id` */,
      },
    },
    {
      id: 'releases',
      test: '/releases/',
      title: 'Releases',
      output: { dir: 'releases', filename: 'feed.rss' },
    },
  ],
});
```

При сборке с указанными выше опциями будет создано два файла: `feeds/blog.xml` и `releases/feed.rss`.

#### `dir`

- **Тип**: `string`
- **По умолчанию**: `rss`

Папка для размещения RSS-файлов (относительно папки `doc_build`).

#### `type`

- **Тип**: `"atom" | "rss" | "json"`
- **По умолчанию**: `atom`

Формат RSS-вывода. По умолчанию используется `atom`:

| Значение | Формат                                                 | Расширение по умолчанию | MIME-тип               |
| -------- | ------------------------------------------------------ | ----------------------- | ---------------------- |
| `atom`   | [Atom 1.0](https://www.ietf.org/rfc/rfc4287.txt)       | `.xml`                  | `application/atom+xml` |
| `rss`    | [RSS 2.0](https://www.rssboard.org/rss-specification)  | `.rss`                  | `application/rss+xml`  |
| `json`   | [JSON Feed 1.1](https://www.jsonfeed.org/version/1.1/) | `.json`                 | `application/json`     |

#### `filename`

- **Тип**: `string`
- **По умолчанию**: в качестве имени файла используется `id` ленты\`; расширение определяется форматом вывода RSS

Изменяет полное имя выходного RSS-файла.

#### `publicPath`

- **Тип**: `string`
- **По умолчанию**: значение `siteUrl`

Префикс URL для RSS-файла. Итоговый URL ленты формируется как `publicPath` + `dir` + `filename`.

#### `sorting`

- **Тип**: `sorting?: (left: FeedItem, right: FeedItem) => number;`

Сортирует статьи. По умолчанию сначала отображаются самые новые статьи.

#### `transform`

- **Тип**: `(content: string, context: { type: 'atom' | 'rss' | 'json'; feed: Feed; channel: FeedChannel }) => string | PromiseLike<string>`

Преобразует финальный сгенерированный контент ленты перед записью на диск. Этот хук доступен как в опции `output` на уровне плагина, так и в опции `output` для каждой ленты, поэтому один и тот же шаблон кастомизации можно использовать для Atom, RSS и JSON Feed.

Например, следующая конфигурация добавляет пользовательский `folo:id` в XML-ленты и добавляет тот же идентификатор в JSON Feed:

```ts
pluginRss({
  siteUrl: 'https://example.com/',
  output: {
    transform(content, { type, channel }) {
      if (type === 'json') {
        return JSON.stringify({
          ...JSON.parse(content),
          foloId: channel.id,
        });
      }

      const closingTag = type === 'rss' ? '</channel>' : '</feed>';
      return content.replace(
        closingTag,
        `<folo:id>${channel.id}</folo:id>${closingTag}`,
      );
    },
  },
});
```
