@bdocs/plugin-rss

The @bdocs/plugin-rss plugin automatically generates RSS 2.0 and Atom feeds from your documentation routes. It supports i18n, collection filtering, and requires zero configuration — just install and your site has a feed.

Quick Start

1. Install the package

pnpm add @bdocs/plugin-rss

2. Register the plugin

Add the plugin to the plugins array in your configuration file:

import { defineConfig } from 'boltdocs'
import rssPlugin from '@bdocs/plugin-rss'

export default defineConfig({
  siteUrl: 'https://my-docs.com',
  theme: {
    title: 'My Documentation',
  },
  plugins: [rssPlugin()],
})

3. Build and access your feed

After building your site, your feed is automatically available:

pnpm boltdocs build

• RSS: https://my-docs.com/rss/feed-en.xml
• Atom: https://my-docs.com/rss/atom-en.xml

For i18n sites, each locale gets its own feed:

• https://my-docs.com/rss/feed-en.xml (English)
• https://my-docs.com/rss/feed-es.xml (Spanish)

Concepts & Architecture

How It Works

1. Route Collection: After the SSG build completes, the plugin reads all generated routes from the PluginContext. These are the same routes used to generate your site's pages.

2. Metadata Extraction: For each route, the plugin extracts title, description, excerpt, date, lastUpdated, and author from the route's frontmatter.

3. Feed Generation: The plugin generates valid XML feeds (RSS 2.0 and/or Atom) with proper entity escaping and RFC 2822 / ISO 8601 date formatting.

4. i18n Support: If your config has i18n enabled, the plugin automatically generates a separate feed for each locale. Routes are filtered by their locale prefix (e.g., /es/docs/... goes to the Spanish feed).

5. Output: Feed files are written to the build output directory alongside your static site files.

When Does It Run?

The plugin uses the afterBuild lifecycle hook, which runs immediately after the SSG build succeeds:

To generate feeds during development, set devMode: true in the plugin options.

Configuration

Minimal Setup

The plugin works with zero configuration. It automatically reads from your existing boltdocs.config.ts:

Plugin Options

All options are optional. Pass them to the plugin factory function:

rssPlugin({
  limit: 50,
  format: 'both',
  paths: ['/blog', '/docs'],
})

API Reference

Plugin Options

Generated Files

The plugin writes feed files to the rss/ directory inside the build output:

Feed Item Fields

Each item in the feed corresponds to a documentation route:

Usage Examples

Basic Setup

import { defineConfig } from 'boltdocs'
import rssPlugin from '@bdocs/plugin-rss'

export default defineConfig({
  siteUrl: 'https://docs.example.com',
  plugins: [rssPlugin()],
})

Blog-Only Feed

If you have a blog collection and only want blog posts in your feed:

rssPlugin({
  collections: ['blog'],
  limit: 30,
  format: 'both',
})

Custom Path Filter

Only include routes under /docs/guides:

rssPlugin({
  paths: ['/docs/guides'],
  limit: 10,
})

RSS and Atom Together

Generate both formats simultaneously:

rssPlugin({
  format: 'both',
  limit: 50,
})

Troubleshooting

Feed not generated

• Check siteUrl: The plugin requires siteUrl to be set in your config. Without it, the plugin logs a warning and skips generation.
• Verify build output: Ensure the build completed successfully. The afterBuild hook only runs on successful builds.
• Check routes: The plugin generates feeds from all documentation routes. If no routes exist, the feed will be empty.

Feed has no items

• Check route filters: If you're using paths or collections, ensure your routes match the filter criteria.
• Check draft flag: Routes with draft: true in frontmatter are excluded from the feed.
• Verify frontmatter: Routes need at least a title to appear in the feed. Items without date or lastUpdated use the current timestamp.

i18n feeds missing

• Verify i18n config: Ensure i18n.defaultLocale and i18n.locales are properly configured.
• Check route locale prefixes: Routes must have locale prefixes (e.g., /es/docs/...) to be included in locale-specific feeds.

Wrong feed title

The feed title is derived from theme.title. If your title is an i18n object ({ en: 'Docs', es: 'Documentación' }), the plugin uses the matching locale key. If no match is found, it falls back to the first value.