使用 feed 为文档中的某些页面生成 RSS 文件。
修改 rspress.config.ts
引入插件
默认配置下,该插件会为所有路由为 /blog/
开头的文档在 doc_build/rss/
文件夹中生成一份名为 blog.xml
的文件,可以通过 /rss/blog.xml
访问。
该插件仅工作于 build 阶段,在 dev 阶段不会生成 RSS 文件。
可以通过 feed.test
参数来选择要包含在 RSS 文件中的文档。
所有包含在 RSS 内的文档都需要含有 date
或 published_at
的 frontmatter,以确保 RSS 在用户侧的更新是稳定的。
通常情况下,你会有输出多个 RSS 文件的需要,比如按语言区分、按类目区分。
可以为 feed
传一组 RSS 配置来实现。比如
以上配置会输出四个 RSS 文件,分别为 blog.xml
、blog-zh.xml
、rspack.xml
、rsbuild.xml
,均在 rss
文件夹中。
可以通过 output
以及 feed.output
参数来修改输出路径。
请参考下文的 FeedOutputOptions。
默认情况下,该插件会在被选择纳入 RSS 的页面中插入一个 <link rel="alternate">
标签,链接到 RSS 文件的 URL。RSS 阅读器能够自动识别到 RSS URL。
如果你想在没被纳入 RSS 的页面(比如首页)中也插入这个标签,可以在文档中添加 link-rss
这个 frontmatter,取值为 feed id。比如
link-rss
也支持在单个页面插入多个 feed id 关联的 <link>
标签:
RSS 文件由两部分组成,一部分是 RSS 的基础信息,在 RSS 格式中称为 channel
,另一部分是文章列表,在 RSS 格式中称为 item
。
其中:
插件的选项。
siteUrl
string
当前文档站点的站点 URL。将在 RSS 文件中使用。
feed
FeedChannel | FeedChannel[]
{ id: 'blog', test: '/blog/' }
RSS 配置,多值数组可以生成多个 RSS 文件。
详见 FeedChannel。
output
Omit<FeedOutputOptions, "filename">
{ dir: 'rss', type: 'atom' }
文档输出配置。请参考下文的 FeedOutputOptions。
id
string
RSS 的 ID,在多个 RSS 配置中唯一。同时也是该 RSS 文件的默认文件名。
test
RegExp | string | (RegExp | string)[] | ((item: PageIndexInfo, base: string) => boolean)
用于匹配文档。匹配上的文档会纳入该 RSS 中。类型说明:
RegExp
: 正则匹配文档的路由。当文档设有 base
时,会同时匹配含 base
和不含 base
的路由。string
: 前缀匹配文档的路由。当文档设有 base
时,会同时匹配含 base
和不含 base
的路由。(item: PageIndexInfo, base: string) => boolean
: 根据文档基础信息和 frontmatter 来匹配页面。item
(item: FeedItem, page: PageIndexInfo, siteUrl: string) => FeedItem | PromiseLike<FeedItem>
生成 RSS 文件中每一篇文章的结构化数据。
结构化数据的的类型请参考:
该插件内置有一个生成逻辑,会充分利用文档的 frontmatter 和页面数据,比如 RSS 中的 content
会优先取 frontmatter 中的 summary
,再尝试取文章内容。
你可以传入一个函数来修改内置逻辑生成的数据,该数据会作为第一个参数传给你传入的这个函数。比如下方配置可以截断 RSS 中的文章内容:
默认逻辑详情请参考:
output
FeedOutputOptions
output
参数相比插件的 output
参数,多一个 filename
,用于修改输出的文件名。
请参考下文的 FeedOutputOptions。
FeedChannel
还继承了 feed package 的 FeedOptions
,未列出的参数请参考
RSS 的输出配置,在插件参数顶层和 feed
这一层都有该配置。使用以下类型。
一个例子:
以上配置将输出 feeds/blog.xml
、releases/feed.rss
两个文件。
dir
string
rss
RSS 文件的输出文件夹,相对于 doc_build
的相对位置。
type
"atom" | "rss" | "json"
atom
修改 RSS 文件的输出格式,默认为 atom
。不同类型的说明如下:
值 | 格式 | 默认后缀名 | MIME Type |
---|---|---|---|
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
修改 RSS 文件的输出完整文件名。
publicPath
string
siteUrl
的值作为默认值RSS 文件 URL 的前缀。一个 RSS URL 由 publicPath
、dir
、filename
共同组成。
sorting
sorting?: (left: FeedItem, right: FeedItem) => number;
可以对 RSS 文件中的文章进行排序。默认情况下是新的文章在前,旧的文章在后。