@rspress/plugin-rss
Исходный код

Генерация RSS-лент для выбранных страниц документации с помощью библиотеки feed.

Установка

npm

yarn

pnpm

bun

deno

npm add @rspress/plugin-rss -D

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

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.

Подсказка

Плагин работает только при выполнении rspress build и не генерирует RSS-файлы в режиме rspress dev.

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

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

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

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

Требования

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

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

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

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

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

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

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 ниже.

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

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

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

---
link-rss: blog
---

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

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

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

---
link-rss:
  - blog
  - releases
---

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

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

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

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

channel полностью настраивается через параметр feed. Подробности — в разделе Другие опции ниже.
item полностью настраивается через параметр feed.item. Подробности — в разделе item ниже.

Опции

PluginRssOptions

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

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

`siteUrl`

Тип: string
По умолчанию: siteOrigin + base, либо base, если siteOrigin не задан

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

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

Если в Rspress настроены параметры siteOrigin и base, параметр siteUrl на уровне плагина можно не указывать. Полный URL формируется в следующем порядке: siteOrigin + base + routePath. Если не заданы ни siteUrl на уровне плагина, ни siteOrigin, плагин использует в качестве резервного варианта значение base. Это сохраняет существующее поведение с относительными путями, но не позволяет генерировать абсолютные RSS-ссылки.

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

`output`

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

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

FeedChannel

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

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

Совет

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

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

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

`item`

Тип: (item: FeedItem, page: PageIndexInfo, siteUrl: string) => FeedItem | PromiseLike<FeedItem>
По умолчанию:
Исходный код

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

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

Исходный код

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

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

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

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

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

`output`

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

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

См. подробности в FeedOutputOptions ниже.

Другие опции

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

Исходный код

FeedOutputOptions

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

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

Пример:

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	`.xml`	`application/atom+xml`
`rss`	RSS 2.0	`.rss`	`application/rss+xml`
`json`	JSON Feed 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:

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}`,
      );
    },
  },
});

#@rspress/plugin-rss Исходный код

#Установка

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

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

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

#Требования

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

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

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

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

#Опции

#PluginRssOptions

#siteUrl

#feed

#output

#FeedChannel

#id

#test

#item

#output

#Другие опции

#FeedOutputOptions

#dir

#type

#filename

#publicPath

#sorting

#transform

@rspress/plugin-rss
Исходный код

Установка

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

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

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

Требования

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

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

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

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

Опции

PluginRssOptions

`siteUrl`

`feed`

`output`

FeedChannel

`id`

`test`

`item`

`output`

Другие опции

FeedOutputOptions

`dir`

`type`

`filename`

`publicPath`

`sorting`

`transform`