Skip to content

RSS Feeds

RSS (Really Simple Syndication) feeds allow users to subscribe to your documentation updates and receive notifications when new content is published. This guide covers RSS feed implementation and configuration using the mkdocs-rss-plugin.

Overview

The MkDocs4 Ultimate Guide includes RSS feed functionality that:

  • Automatically generates RSS 2.0 feeds for blog posts
  • Integrates seamlessly with the Material for MkDocs blog plugin
  • Includes post metadata (categories, tags, authors)
  • Provides tracking parameters for analytics
  • Is automatically discovered by browsers and feed readers

Features

Automatic Generation

RSS feeds are generated automatically during the build process, including: - feed_rss_created.xml - Posts ordered by creation date - feed_rss_updated.xml - Posts ordered by update date

Content Filtering

Only blog posts are included in RSS feeds: - Uses pattern matching (blog/posts/.*) to filter content - Excludes documentation pages from feeds - Respects draft post settings

Rich Metadata

Each feed item includes: - Post title and content excerpt - Publication and update dates - Author information - Categories and tags - Comments link integration

Configuration

RSS Plugin Setup

The RSS plugin is configured in mkdocs.yml:

plugins:
  - rss:
      match_path: "blog/posts/.*"       # Only include blog posts
      date_from_meta:
        as_creation: "date"             # Use 'date' meta for creation
        datetime_format: "%Y-%m-%d"     # Expected date format
        default_timezone: "UTC"         # Default timezone
      categories:
        - tags                          # Include tags as categories
        - categories                    # Include categories as categories
      comments_path: "#__comments"      # Path to comments section
      image: "assets/logo.svg"          # RSS feed image
      abstract_chars_count: 160        # Character limit for descriptions
      abstract_delimiter: "<!-- more -->"  # Use blog excerpt delimiter
      feed_ttl: 1440                    # Cache time (24 hours)
      length: 20                        # Number of posts in feed
      pretty_print: true                # Format RSS for readability
      url_parameters:                   # Add tracking parameters
        utm_source: "documentation"
        utm_medium: "RSS"

Blog Integration

RSS feeds work seamlessly with the blog plugin:

plugins:
  - blog:
      post_excerpt_separator: <!-- more -->  # Shared with RSS
      categories: true                       # RSS includes categories
      # ... other blog settings
  - rss:
      abstract_delimiter: "<!-- more -->"    # Same as blog excerpt
      categories:
        - tags
        - categories

Material Theme Integration

Material for MkDocs automatically adds RSS feed links to the HTML <head>:

<link rel="alternate" type="application/rss+xml"
      title="Ultimate MkDocs Material Guide - RSS Feed"
      href="/feed_rss_created.xml">

Usage Examples

Blog Post with RSS Metadata

Create blog posts with proper metadata:

---
date: 2024-01-15
categories:
  - Documentation
  - Tutorial
tags:
  - mkdocs
  - rss
  - automation
authors:
  - john_doe
---

# Getting Started with MkDocs

This is the post introduction that will appear in RSS feeds.

<!-- more -->

The rest of the content appears only in the full post...

Feed Discovery

RSS feeds are automatically discoverable:

  • Browsers show RSS icon in address bar
  • Feed readers can auto-detect feeds
  • Search engines index feed content

Analytics Integration

Track RSS subscribers with UTM parameters:

  • utm_source=documentation - Identifies source
  • utm_medium=RSS - Identifies medium
  • Custom parameters can be added

Validation and Testing

RSS Feed Validation

Validate generated feeds:

  1. W3C Feed Validator: https://validator.w3.org/feed/
  2. RSS Validator: http://www.rssboard.org/rss-validator/
  3. FeedValidator.org: https://feedvalidator.org/

Testing with Feed Readers

Test RSS feeds with popular readers:

Verification Commands

# Check feed generation
ls site/feed_*.xml

# Validate XML structure
xmllint --noout site/feed_rss_created.xml

# Test HTTP headers (when served)
curl -I https://your-site.com/feed_rss_created.xml

Feed Formats

RSS 2.0 Features

Generated feeds include:

  • Channel metadata: Title, description, link, language
  • Item metadata: Title, description, publication date
  • Dublin Core: Enhanced metadata support
  • Atom namespace: Modern RSS features

Feed Structure

<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
  <channel>
    <title>Ultimate MkDocs Material Guide</title>
    <description>The definitive guide to MkDocs Material</description>
    <link>https://mkdocs-ultimate.example.com/</link>
    <atom:link href="https://mkdocs-ultimate.example.com/feed_rss_created.xml"
               rel="self" type="application/rss+xml" />
    <item>
      <title>Post Title</title>
      <description>Post excerpt...</description>
      <link>https://mkdocs-ultimate.example.com/blog/posts/...</link>
      <pubDate>Mon, 15 Jan 2024 00:00:00 +0000</pubDate>
      <category>Documentation</category>
    </item>
  </channel>
</rss>

Best Practices

Content Strategy

  1. Consistent posting: Regular content updates
  2. Excerpt optimization: Clear, compelling post excerpts
  3. Category organization: Logical category structure
  4. SEO optimization: Descriptive titles and content

Technical Optimization

  1. Feed caching: Configure appropriate TTL values
  2. Image optimization: Use absolute URLs for images
  3. Link validation: Ensure all links are absolute
  4. Mobile compatibility: Test on mobile feed readers

Analytics and Monitoring

  1. Subscriber tracking: Monitor RSS analytics
  2. Click tracking: Use UTM parameters
  3. Content performance: Track which posts perform best
  4. Feed health: Regular validation and testing

Troubleshooting

Common Issues

Empty RSS Feed

  • Cause: No blog posts match the match_path pattern
  • Solution: Verify blog post locations and pattern

Invalid dates

  • Cause: Incorrect date format in post metadata
  • Solution: Use ISO format: YYYY-MM-DD

Missing metadata

  • Cause: Posts lack required frontmatter
  • Solution: Add date, title, and other metadata

Feed validation errors

  • Cause: Invalid XML or missing required elements
  • Solution: Check logs and validate feed structure

Debug Commands

# Check RSS plugin output
mkdocs build --verbose

# Validate XML structure
xmllint --format site/feed_rss_created.xml

# Test feed parsing
python -c "
import feedparser
feed = feedparser.parse('site/feed_rss_created.xml')
print(f'Title: {feed.feed.title}')
print(f'Entries: {len(feed.entries)}')
"

External Resources