feed

Generate feeds for your VuePress site.

Usage

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,
    }),
  ],
}

The plugin can generate the following formats. Enable the ones you need:

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

The hostname option is required, as the feed links are generated from it.

Readable Preview

Atom and RSS feeds include XSL templates, so they are rendered as human-readable HTML when opened in a browser. See the Atom and RSS feeds of this site for a live example.

To preview feeds in the development server, set devServer: true, and configure devHostname if your local address differs from the default http://localhost:{port}.

Channel Metadata

The channel option configures the metadata shared by all the generated feeds. It is recommended to set channel.pubDate, channel.ttl, channel.copyright and channel.author.

Item Generation

By default, every page generated from a Markdown file is included in the feed, except the homepage. You can:

exclude a single page, or override the fields of its feed item, with the feed frontmatter;
take full control of the item generation with the getter option.

Items are sorted by the page creation time from git, falling back to the date frontmatter. @vuepress/plugin-git must be enabled to have the creation time, otherwise the items follow the default page order.

I18n

The plugin generates a separate feed for each locale, which can be configured with the locales option.

Options

hostnameRequiredstring

The hostname where the site is deployed, e.g. https://example.com.

atomboolean

Whether to generate an Atom 1.0 feed.

jsonboolean

Whether to generate a JSON 1.1 feed.

rssboolean

Whether to generate an RSS 2.0 feed.

countnumber

Default100

The maximum number of items in each feed.

imagestring

The image of the feeds, used as a banner.

iconstring

The icon of the feeds, used as a favicon.

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

The elements to preserve in the feed content. All other unknown tags are removed.

filter(page: Page) => boolean

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

A function to determine whether a page is included in the feed.

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

A function to sort the feed items.

Channel Options

Details

titlestring

Default The title of the locale

The title of the channel.

linkstring

Default The deployment link of the locale

The address of the site the channel stands for.

descriptionstring

Default The description of the locale

The description of the channel.

languagestring

Default The lang of the locale

The language of the channel.

copyrightrecommended: Yesstring

Default Copyright by the author name

The copyright notice of the channel.

pubDaterecommended: YesDate

Default The time when the plugin is invoked

The publication date of the channel.

lastUpdatedDate

Default The time when the plugin is invoked

The last updated time of the channel content.

ttlrecommended: Yesnumber

The number of minutes a feed reader may cache the content before refreshing it.

imagerecommended: Yesstring

The image of the channel, a square image of at least 512×512 pixels is recommended.

iconrecommended: Yesstring

The icon of the channel, a square image of at least 128×128 pixels with a transparent background is recommended.

authorrecommended: YesFeedAuthor | FeedAuthor[]

The primary author of the channel.

interface FeedAuthor {
  name?: string
  email?: string
  /** json feed only */
  url?: string
  /** json feed only */
  avatar?: string
}

hubstring

The URL of the WebSub hub, see WebSub.

Getter Options

Details

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

Get the title of the feed item.

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

Get the link of the feed item.

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

Get the description of the feed item.

Atom supports HTML in the description, return a string prefixed with html: to have it rendered.

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

Get the excerpt of the feed item.

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

Get the content of the feed item.

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

Get the authors of the feed item. Return an empty array when there is no author.

interface FeedAuthor {
  name?: string
  email?: string
  /** json feed only */
  url?: string
  /** json feed only */
  avatar?: string
}

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

Get the categories of the feed item.

interface FeedCategory {
  name: string
  /** rss format only */
  domain?: string
  /** atom format only */
  scheme?: string
}

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

Get the enclosure of the feed item.

interface FeedEnclosure {
  url: string
  /** should be a standard MIME type, rss format only */
  type: string
  /** rss format only */
  length?: number
}

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

Get the publish date of the feed item.

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

Get the last update date of the feed item.

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

Get the image of the feed item. Return a complete absolute URL.

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

Get the contributors of the feed item. Return an empty array when there is no contributor.

interface FeedContributor {
  name?: string
  email?: string
  /** json feed only */
  url?: string
  /** json feed only */
  avatar?: string
}

Get the copyright of the feed item.

Frontmatter

Inclusion Control

By default, every page generated from a Markdown file is included in the feed, except the homepage. Set feed: false in the frontmatter to exclude a page.

Standard Information

The following standard frontmatter properties are read automatically.

titlestring

The title of the page, which falls back to the first h1 header.

descriptionstring

The description of the page.

dateDate

The publish date of the page, used by the default feed item sorter.

authorAuthorInfo | AuthorInfo[] | string | string[]

The author of the page. An object author should have a name field, and can have optional url and email fields.

The copyright of the page.

coverstring

The cover image of the page, which must be a complete URL or an absolute path.

string

The banner image of the page, which takes priority over cover and is used as the feed item image. When neither is set, the first image of the page content is used.

Feed Options

The feed frontmatter overrides the standard properties or provides fields specific to the feed item.

feedFeedFrontmatterOption | false

Whether to include the page in the feed, or the feed item config of the page.

feed.titlestring

The title used for the feed item.

feed.descriptionstring

The description used for the feed item, which should be plain text.

feed.summarystring

The summary used for the feed item, which should be HTML content.

feed.contentstring

The content used for the feed item, which defaults to the page content.

feed.authorFeedAuthor | FeedAuthor[]

The authors of the feed item.

interface FeedAuthor {
  name?: string
  email?: string
  /** json feed only */
  url?: string
  /** json feed only */
  avatar?: string
}

feed.contributorFeedContributor | FeedContributor[]

The contributors of the feed item.

interface FeedContributor {
  name?: string
  email?: string
  /** json feed only */
  url?: string
  /** json feed only */
  avatar?: string
}

feed.categoryFeedCategory | FeedCategory[]

The categories of the feed item.

interface FeedCategory {
  name: string
  /** rss format only */
  domain?: string
  /** atom format only */
  scheme?: string
}

feed.guidstring

The globally unique identifier of the feed item, which defaults to its link.