diff --git a/packages/document/docs/en/plugin/official-plugins/rss.mdx b/packages/document/docs/en/plugin/official-plugins/rss.mdx index 1efda962b..0cf04c604 100644 --- a/packages/document/docs/en/plugin/official-plugins/rss.mdx +++ b/packages/document/docs/en/plugin/official-plugins/rss.mdx @@ -22,7 +22,7 @@ export default defineConfig({ // The URL of your document site siteUrl: 'https://example.com', // ...more configurations below - }) + }), ], }); ``` @@ -44,8 +44,8 @@ Use the `feed.test` option to select which pages to be included in the RSS file. ```ts pluginRss({ // ... - feed: { test: '/zh/blog' } -}) + feed: { test: '/zh/blog' }, +}); ``` ### Requirements @@ -70,11 +70,26 @@ You can provide a list of RSS options to the `feed` option. For instance: 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' }, - ] -}) + { + 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. @@ -101,6 +116,16 @@ This frontmatter will insert a `` tag in the page of thi However, this page itself will not be included in that RSS. ``` +`link-rss` also supports inserting multiple `` tags associated with feed ids on a single page: + +```markdown +--- +link-rss: + - blog + - releases +--- +``` + ### Cook the 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. @@ -204,7 +229,10 @@ You can provide the `item` function to modify the generated data which will be p For example, the following configuration truncates the content of articles in the RSS: ```ts -const item: FeedChannel['item'] = (item) => ({...item, content: item.content.slice(0, 1000)}); +const item: FeedChannel['item'] = item => ({ + ...item, + content: item.content.slice(0, 1000), +}); ``` For details on the logic of the built-in generator, please refer to: @@ -229,7 +257,7 @@ Output options for RSS files, available at both the top level of the plugin opti ```ts interface FeedOutputOptions { dir?: string; - type?: "atom" | "rss" | "json"; + type?: 'atom' | 'rss' | 'json'; filename?: string; publicPath?: string; } @@ -244,13 +272,25 @@ pluginRss({ // 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' + 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' } }, - ] -}) + { + 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`. @@ -269,11 +309,11 @@ Output folder for RSS files, relative to `doc_build`. Output format of the RSS file, `atom` by default. Details of these types: -| Value | Format | Default Extension | MIME Type | -|-------|-----------------------------------------------------------|-------------------|------------------------| -| `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` | +| Value | Format | Default Extension | MIME Type | +| ------ | ------------------------------------------------------ | ----------------- | ---------------------- | +| `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` diff --git a/packages/document/docs/zh/plugin/official-plugins/rss.mdx b/packages/document/docs/zh/plugin/official-plugins/rss.mdx index c49678f67..a817a8c99 100644 --- a/packages/document/docs/zh/plugin/official-plugins/rss.mdx +++ b/packages/document/docs/zh/plugin/official-plugins/rss.mdx @@ -24,7 +24,7 @@ export default defineConfig({ // 你的文档站点的 url siteUrl: 'https://example.com', // ...更多配置请见下文 - }) + }), ], }); ``` @@ -44,8 +44,8 @@ export default defineConfig({ ```ts pluginRss({ // ... - feed: { test: '/zh/blog' } -}) + feed: { test: '/zh/blog' }, +}); ``` ### 文档要求 @@ -70,11 +70,26 @@ published_at: 2024-01-10 08:00:00 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' }, - ] -}) + { + 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', + }, + ], +}); ``` 以上配置会输出四个 RSS 文件，分别为 `blog.xml`、`blog-zh.xml`、`rspack.xml`、`rsbuild.xml`，均在 `rss` 文件夹中。 @@ -101,11 +116,22 @@ link-rss: blog 但这个页面自身不会被纳入该 RSS。 ``` +`link-rss` 也支持在单个页面插入多个 feed id 关联的 `` 标签： + +```markdown +--- +link-rss: + - blog + - releases +--- +``` + ### 修改输出的 RSS 内容 RSS 文件由两部分组成，一部分是 RSS 的基础信息，在 RSS 格式中称为 `channel`，另一部分是文章列表，在 RSS 格式中称为 `item`。 其中： + - `channel` 可以由 `feed` 这个参数完全控制，请参考下文的 [其他参数](#其他参数)。 - `item` 可以由 `feed.item` 这个参数完全控制，请参考下文的 [item](#item)。 @@ -197,7 +223,10 @@ RSS 的 ID，在多个 RSS 配置中唯一。同时也是该 RSS 文件的默认 你可以传入一个函数来修改内置逻辑生成的数据，该数据会作为第一个参数传给你传入的这个函数。比如下方配置可以截断 RSS 中的文章内容： ```ts -const item: FeedChannel['item'] = (item) => ({...item, content: item.content.slice(0, 1000)}); +const item: FeedChannel['item'] = item => ({ + ...item, + content: item.content.slice(0, 1000), +}); ``` 默认逻辑详情请参考： @@ -222,7 +251,7 @@ RSS 的输出配置，在插件参数顶层和 `feed` 这一层都有该配置 ```ts interface FeedOutputOptions { dir?: string; - type?: "atom" | "rss" | "json"; + type?: 'atom' | 'rss' | 'json'; filename?: string; publicPath?: string; } @@ -237,13 +266,23 @@ pluginRss({ // 将 RSS 文件输出文件夹改为 `feeds`，该值为相对于 `doc_build` 的位置 dir: 'feeds', // 输出为 RSS 2.0 格式，默认为 .rss 后缀。 - type: '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' } }, - ] -}) + { + 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` 两个文件。 @@ -262,11 +301,11 @@ RSS 文件的输出文件夹，相对于 `doc_build` 的相对位置。 修改 RSS 文件的输出格式，默认为 `atom`。不同类型的说明如下： -| 值 | 格式 | 默认后缀名 | MIME Type | -|---|-------------------------------------------------------|--------|---| -| `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` | +| 值 | 格式 | 默认后缀名 | MIME Type | +| ------ | ------------------------------------------------------ | ---------- | ---------------------- | +| `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`