feed

为你的 VuePress 站点生成 Feed。

使用

npm i -D @vuepress/plugin-feed@next

.vuepress/config.ts
import { feedPlugin } from '@vuepress/plugin-feed'

export default {
  plugins: [
    feedPlugin({
      hostname: 'https://example.com',
      atom: true,
    }),
  ],
}

插件可以生成以下格式的 Feed，启用你需要的格式即可：

Atom 1.0：atom
JSON 1.1：json
RSS 2.0：rss

hostname 选项是必须的，Feed 链接由它生成。

可视化预览

Atom 和 RSS Feed 内置了 XSL 模板，因此在浏览器中打开时会渲染为易于阅读的 HTML 页面。你可以查看本站的 Atom 和 RSS Feed 作为示例。

如果你希望在开发服务器中预览 Feed，请设置 devServer: true；如果你的本地地址不是默认的 http://localhost:{port}，还需要配置 devHostname。

频道信息

channel 选项用于配置所有 Feed 共用的频道信息。推荐设置 channel.pubDate、channel.ttl、channel.copyright 和 channel.author。

参考：频道选项。

条目生成

默认情况下，除首页外所有由 Markdown 文件生成的页面都会被添加到 Feed 中。你可以：

通过 feed Frontmatter 移除单个页面，或覆盖该页面 Feed 条目的字段；
通过 getter 选项完全控制条目的生成逻辑。

条目默认按照 Git 中的页面创建时间排序，并在缺少创建时间时回退到 date Frontmatter。你需要启用 @vuepress/plugin-git 才能获取创建时间，否则条目会遵循 VuePress 默认的页面顺序。

多语言支持

插件会为每种语言生成独立的 Feed，你可以通过 locales 选项为不同语言提供特定配置。

选项

hostname必填string

站点部署的域名，例如 https://example.com。

atomboolean

是否生成 Atom 1.0 Feed。

jsonboolean

是否生成 JSON 1.1 Feed。

rssboolean

是否生成 RSS 2.0 Feed。

countnumber

默认值100

每个 Feed 中最多包含的条目数量。

imagestring

Feed 的图片，用作横幅。

iconstring

Feed 的图标，用作网站图标。

preservedElements(RegExp | string)[] | (tagName: string) => boolean

需要在 Feed 内容中保留的元素。除此之外的未知标签都会被移除。

filter(page: Page) => boolean

默认值({ frontmatter, filePathRelative }) => Boolean(frontmatter.feed ?? (filePathRelative && !frontmatter.home))

用于判断页面是否包含在 Feed 中的函数。

sorter(pageA: Page, pageB: Page) => number

用于对 Feed 条目排序的函数。

参考：条目生成。

channelPartial<FeedChannelOptions>

生成 Feed 的频道信息。

参考：频道选项。

getterFeedGetter

Feed 条目生成逻辑的控制器，默认使用内置的 getter。

参考：获取器选项。

devServerboolean

是否在开发服务器中生成 Feed。

devHostnamestring

默认值'http://localhost:${port}'

开发服务器中使用的域名。

atomOutputFilenamestring

默认值'atom.xml'

Atom Feed 的输出文件名，相对于输出目录。

atomXslTemplatestring

Atom Feed 的 XSL 模板内容，默认为内置的 atom.xsl。

atomXslFilenamestring

默认值'atom.xsl'

Atom XSL 文件的输出文件名，相对于输出目录。

jsonOutputFilenamestring

默认值'feed.json'

JSON Feed 的输出文件名，相对于输出目录。

rssOutputFilenamestring

默认值'rss.xml'

RSS Feed 的输出文件名，相对于输出目录。

rssXslTemplatestring

RSS Feed 的 XSL 模板内容，默认为内置的 rss.xsl。

rssXslFilenamestring

默认值'rss.xsl'

RSS XSL 文件的输出文件名，相对于输出目录。

localesRecord<string, BaseFeedPluginOptions>

针对特定语言的配置。除 hostname 外，上述所有选项均受支持。

频道选项

详情

titlestring

默认值该语言的标题

频道的标题。

linkstring

默认值该语言的部署链接

频道对应的站点地址。

descriptionstring

默认值该语言的描述

频道的描述。

languagestring

默认值该语言的 lang

频道的语言。

copyrightrecommended: Yesstring

默认值 Copyright by 作者名称

频道的版权信息。

pubDaterecommended: YesDate

默认值插件被调用的时间

频道的发布时间。

lastUpdatedDate

默认值插件被调用的时间

频道内容的最后更新时间。

ttlrecommended: Yesnumber

Feed 阅读器在刷新前可以缓存内容的分钟数。

imagerecommended: Yesstring

频道的图片，建议使用尺寸不小于 512×512 的方形图片。

iconrecommended: Yesstring

频道的图标，建议使用尺寸不小于 128×128 且背景透明的方形图片。

authorrecommended: YesFeedAuthor | FeedAuthor[]

频道的主要作者。

interface FeedAuthor {
  name?: string
  email?: string
  /** 仅限 json 格式 */
  url?: string
  /** 仅限 json 格式 */
  avatar?: string
}

hubstring

WebSub 的链接，请参阅 WebSub。

获取器选项

详情

title(page: Page, app: App) => string

获取 Feed 条目的标题。

link(page: Page, app: App) => string

获取 Feed 条目的链接。

description(page: Page, app: App) => string | null

获取 Feed 条目的描述。

Atom 支持在描述中使用 HTML，返回以 html: 开头的字符串即可。

excerpt(page: Page, app: App) => string | null

获取 Feed 条目的摘要。

content(page: Page, app: App) => string

获取 Feed 条目的正文内容。

author(page: Page, app: App) => FeedAuthor[]

获取 Feed 条目的作者。缺少作者信息时应返回空数组。

interface FeedAuthor {
  name?: string
  email?: string
  /** 仅限 json 格式 */
  url?: string
  /** 仅限 json 格式 */
  avatar?: string
}

category(page: Page, app: App) => FeedCategory[] | null

获取 Feed 条目的分类。

interface FeedCategory {
  name: string
  /** 仅限 rss 格式 */
  domain?: string
  /** 仅限 atom 格式 */
  scheme?: string
}

enclosure(page: Page, app: App) => FeedEnclosure | null

获取 Feed 条目的媒体附件。

interface FeedEnclosure {
  url: string
  /** 应为标准 MIME 类型，仅限 rss 格式 */
  type: string
  /** 仅限 rss 格式 */
  length?: number
}

publishDate(page: Page, app: App) => Date | null

获取 Feed 条目的发布日期。

lastUpdateDate(page: Page, app: App) => Date

获取 Feed 条目的最后修改日期。

image(page: Page, app: App) => string

获取 Feed 条目的图片，需要返回完整的绝对 URL。

contributor(page: Page, app: App) => FeedContributor[]

获取 Feed 条目的贡献者。缺少贡献者信息时应返回空数组。

interface FeedContributor {
  name?: string
  email?: string
  /** 仅限 json 格式 */
  url?: string
  /** 仅限 json 格式 */
  avatar?: string
}

获取 Feed 条目的版权信息。

页面标题，默认回退到第一个 h1 标题。

descriptionstring

页面的描述。

dateDate

页面的发布日期，会被默认的 Feed 条目排序器使用。

authorAuthorInfo | AuthorInfo[] | string | string[]

页面的作者。对象形式的作者需要含有 name 字段，可以含有可选的 url 和 email 字段。

页面的版权信息。

coverstring

页面的封面图片，必须是完整的 URL 链接或绝对路径。

string

页面的横幅图片，优先级高于 cover，会被用作 Feed 条目的图片。两者都未设置时，会使用页面内容中的第一张图片。

Feed 选项

feed Frontmatter 用于覆盖上述标准属性，或提供 Feed 条目专用的字段。

feedFeedFrontmatterOption | false

是否将页面包含在 Feed 中，或该页面的 Feed 条目配置。

feed.titlestring

该 Feed 条目的标题。

feed.descriptionstring

该 Feed 条目的描述，应为纯文本。

feed.summarystring

该 Feed 条目的摘要，应为 HTML 内容。

feed.contentstring

该 Feed 条目的内容，默认为页面内容。

feed.authorFeedAuthor | FeedAuthor[]

该 Feed 条目的作者。

interface FeedAuthor {
  name?: string
  email?: string
  /** 仅限 json 格式 */
  url?: string
  /** 仅限 json 格式 */
  avatar?: string
}

feed.contributorFeedContributor | FeedContributor[]

该 Feed 条目的贡献者。

interface FeedContributor {
  name?: string
  email?: string
  /** 仅限 json 格式 */
  url?: string
  /** 仅限 json 格式 */
  avatar?: string
}

feed.categoryFeedCategory | FeedCategory[]

该 Feed 条目的分类。

interface FeedCategory {
  name: string
  /** 仅限 rss 格式 */
  domain?: string
  /** 仅限 atom 格式 */
  scheme?: string
}

feed.guidstring

该 Feed 条目的全局唯一标识符，默认为条目的链接。