Skip to content

Commit

Permalink
docs(plugin-rss): add multiple links example (#912)
Browse files Browse the repository at this point in the history
  • Loading branch information
@chenjiahan
chenjiahan authored Apr 6, 2024
1 parent 44658dc commit 03a9ae0
Show file tree
Hide file tree
Showing 2 changed files with 119 additions and 40 deletions.
80 changes: 60 additions & 20 deletions packages/document/docs/en/plugin/official-plugins/rss.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ export default defineConfig({
// The URL of your document site
siteUrl: 'https://example.com',
// ...more configurations below
})
}),
],
});
```
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -101,6 +116,16 @@ This frontmatter will insert a `<link rel="alternative">` tag in the page of thi
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:

```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.
Expand Down Expand Up @@ -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: <SourceCode href="https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-rss/src/feed.ts" />
Expand All @@ -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;
}
Expand All @@ -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`.
Expand All @@ -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`

Expand Down
79 changes: 59 additions & 20 deletions packages/document/docs/zh/plugin/official-plugins/rss.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ export default defineConfig({
// 你的文档站点的 url
siteUrl: 'https://example.com',
// ...更多配置请见下文
})
}),
],
});
```
Expand All @@ -44,8 +44,8 @@ export default defineConfig({
```ts
pluginRss({
// ...
feed: { test: '/zh/blog' }
})
feed: { test: '/zh/blog' },
});
```

### 文档要求
Expand All @@ -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` 文件夹中。
Expand All @@ -101,11 +116,22 @@ link-rss: blog
但这个页面自身不会被纳入该 RSS。
```

`link-rss` 也支持在单个页面插入多个 feed id 关联的 `<link>` 标签：

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

### 修改输出的 RSS 内容

RSS 文件由两部分组成，一部分是 RSS 的基础信息，在 RSS 格式中称为 `channel`，另一部分是文章列表，在 RSS 格式中称为 `item`。

其中：

- `channel` 可以由 `feed` 这个参数完全控制，请参考下文的 [其他参数](#其他参数)。
- `item` 可以由 `feed.item` 这个参数完全控制，请参考下文的 [item](#item)。

Expand Down Expand Up @@ -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),
});
```

默认逻辑详情请参考：<SourceCode href="https://github.com/web-infra-dev/rspress/tree/main/packages/plugin-rss/src/feed.ts" />
Expand All @@ -222,7 +251,7 @@ RSS 的输出配置，在插件参数顶层和 `feed` 这一层都有该配置
```ts
interface FeedOutputOptions {
dir?: string;
type?: "atom" | "rss" | "json";
type?: 'atom' | 'rss' | 'json';
filename?: string;
publicPath?: string;
}
Expand All @@ -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` 两个文件。
Expand All @@ -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`

Expand Down

0 comments on commit 03a9ae0

Please sign in to comment.