#@rspress/plugin-rss

Source Code

Generates RSS files for selected documentation pages with feed.

#Installation

npm add @rspress/plugin-rss -D

yarn add @rspress/plugin-rss -D

pnpm add @rspress/plugin-rss -D

bun add @rspress/plugin-rss -D

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

#Update Rspress config

import { defineConfig } from '@rspress/core';
import { pluginRss } from '@rspress/plugin-rss';

export default defineConfig({
  plugins: [
    pluginRss({
      // The URL of your documentation site
      siteUrl: 'https://example.com',
      // ...more configurations below
    }),
  ],
});

By default, this plugin generates a blog.xml file in the doc_build/rss/ folder for all pages starting with /blog/.

The RSS file can be accessed via /rss/blog.xml.

#Usage

#Selecting pages to be included in RSS

Use the feed.test option to select which pages are included in the RSS file.

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

#Requirements

All documents included in the RSS must have either date or published_at in frontmatter to keep RSS updates stable for readers.

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

Or frontmatter `date`.

#Generating multiple RSS files

Sometimes you may need to generate multiple RSS files, for example for different languages or categories.

Pass a list of RSS options to feed:

pluginRss({
  feed: [
    { id: 'blog', test: '/blog/', title: 'Rspress Blog', language: 'en-US' },
    {
      id: 'blog-zh',
      test: '/zh/blog/',
      title: 'Rspress 博客',
      language: 'zh-CN',
    },
    {
      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',
    },
  ],
});

The options above will generate four RSS files: blog.xml, blog-zh.xml, rspack.xml, rsbuild.xml, all located in the rss folder.

#Modifying the output path

You can customize the output path using the output and feed.output parameters.

See FeedOutputOptions below.

#Linking RSS to doc pages

By default, this plugin inserts a <link rel="alternate"> tag into selected pages included in the RSS. The tag points to the RSS file URL, so RSS readers can detect it automatically.

To insert this tag into pages that are not included in the RSS, such as the homepage, add link-rss frontmatter with the feed ID as the value. For example:

---
link-rss: blog
---

This frontmatter inserts a `<link rel="alternate">` tag into this page and points it to the RSS URL of the `blog` feed.

However, this page itself will not be included in that RSS.

link-rss also supports inserting multiple <link> tags associated with feed ids on a single page:

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

#Customize RSS content

The RSS file consists of two parts: the RSS basic information, known as the channel in the RSS format, and the list of articles, known as the item in the RSS format.

Customize each part as follows:

• The channel can be fully modified through the feed option. See Other Options below.
• The item can be fully modified through the feed.item option. See the item section below.

#Options

#PluginRssOptions

Plugin options.

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

#siteUrl

• Type: string
• Default: siteOrigin + base, or base when siteOrigin is not configured

The site URL of the current documentation site. It is used in the RSS file.

RSS links are consumed outside the documentation page context, so configure an absolute URL with protocol and domain, such as https://example.com/base/. When base is configured, plugin-level siteUrl must include the base path.

If siteOrigin and base are configured in Rspress, you can omit the plugin-level siteUrl. The full URL concatenation order is siteOrigin + base + routePath. If neither plugin-level siteUrl nor siteOrigin is configured, the plugin falls back to base, which keeps existing relative path behavior but does not generate absolute RSS links.

// 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 defaults to 'https://example.com/base/'
    pluginRss(),
  ],
});

#feed

• Type: FeedChannel | FeedChannel[]
• Default: { id: 'blog', test: '/blog/' }

RSS configuration. Pass an array to generate multiple RSS files.

See FeedChannel for more information.

#output

• Type: Omit<FeedOutputOptions, "filename">
• Default: { dir: 'rss', type: 'atom' }

Output options. See FeedOutputOptions below.

#FeedChannel

RSS file options.

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

• Type: string
• Required

The RSS feed ID, which must be unique across multiple RSS options. It is also the default file basename for the RSS file.

#test

• Type: RegExp | string | (RegExp | string)[] | ((item: PageIndexInfo) => boolean)
• Required

Selects documents to include in the RSS. Supported values:

• RegExp: Regular expression that matches the document route.
• string: Prefix-based match against the document route.
• (item: PageIndexInfo) => boolean: Match pages based on page data and frontmatter. This is also the recommended way to include a route prefix while excluding specific pages such as /blog/.

For example, if you only want to include article pages under /blog/ but exclude the blog index page itself:

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

#item

• Type: (item: FeedItem, page: PageIndexInfo, siteUrl: string) => FeedItem | PromiseLike<FeedItem>
• Default:
  Source Code

Generates structured data for each article in the RSS file.

Refer to the type of structured data:

The plugin has a built-in generator that uses document frontmatter and page data.

For example, RSS content uses summary from frontmatter first, then falls back to document content.

Provide the item function to modify the generated data passed as the first parameter.

For example, the following configuration truncates the content of articles in the RSS:

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

#output

• Type: FeedOutputOptions
• Default: Uses the plugin's output option by default

Compared with the plugin-level output option, this option also includes filename for changing the output filename.

See FeedOutputOptions below.

#Other options

FeedChannel also inherits FeedOptions from the feed package. See

#FeedOutputOptions

RSS output options. They are available both at the plugin level and the feed level, with the following type:

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

Example:

pluginRss({
  // Applied to all RSS outputs
  output: {
    // Change the output folder for RSS files to 'feeds', relative to `doc_build`
    dir: 'feeds',
    // Output in RSS 2.0 format, use `.rss` extension by default.
    type: 'rss',
  },
  feed: [
    {
      id: 'blog',
      test: '/blog/',
      title: 'My Blog',
      output: {
        type: 'atom' /* default to using `id` as the base file name */,
      },
    },
    {
      id: 'releases',
      test: '/releases/',
      title: 'Releases',
      output: { dir: 'releases', filename: 'feed.rss' },
    },
  ],
});

Building with the options above will output two files: feeds/blog.xml and releases/feed.rss.

#dir

• Type: string
• Default: rss

Output folder for RSS files, relative to doc_build.

#type

• Type: "atom" | "rss" | "json"
• Default: atom

RSS output format. The default is atom:

#filename

• Type: string
• Default: ID as the file basename; extension by RSS output format

Modifies the full filename of the RSS file.

#publicPath

• Type: string
• Default: the value of siteUrl

URL prefix for the RSS file. An RSS URL is composed of publicPath, dir, and filename.

#sorting

• Type：sorting?: (left: FeedItem, right: FeedItem) => number;

Sorts articles. By default, newest articles appear first.

#transform

• Type: (content: string, context: { type: 'atom' | 'rss' | 'json'; feed: Feed; channel: FeedChannel }) => string | PromiseLike<string>

Transform the final generated feed content before it is written to disk. This hook is available in both the plugin-level output option and the per-feed output option, so the same customization pattern can be used for Atom, RSS, and JSON Feed outputs.

For example, the following configuration injects a custom folo:id into XML feeds and adds the same identifier to 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}`,
      );
    },
  },
});