Blog aggregation, static-website style!

This is a plugin for the Pelican static site generator.

It allows generating a page aggregating blog articles from other web sites.

Usage

Install this plugin:

$ pip install pelican-feed-planet

Then, in your Pelican config file, enable the plugin:

PLUGINS = [
    ...
    'pelican_planet',
    ...
    ]

Next, declare the feeds you want to aggregate in your Pelican config file:

PLANET_FEEDS = {
    'Some amazing blog': 'https://example1.org/feeds/blog.atom.xml',
    'Another great blog': 'http://example2.org/feeds/blog.atom.xml',
    }

Write a Jinja2 template for your aggregation page. For example, if the rest of your website is generated from Markdown pages, then create a planet.md.tmpl file with the following contents:

Some blogs aggregated here.

{% for article in articles %}
# {{ article.title }}

{% endfor %}

Finally, declare the template and destination page in your Pelican config file:

PLANET_TEMPLATE = 'planet.md.tmpl'
PLANET_PAGE = 'content/planet.md'

Then rebuild your website as usual using the pelican command line, and you should have your blog aggregation page.

You'll probably want to rebuild your website periodically though, maybe with a systemd timer or a cron job, to always fetch the latest articles in the feeds you aggregate.

Template design

The template for your aggregation page will be passed an articles variable, containing the list of articles aggregated.

Each item of this list will have the following attributes:

• title: The title of the article;
• updated: The date at which the article was last updated, as a timezone-aware datetime object;
• author: The author of the article;
• link: The URL to the article on its original website;
• summary: The summary text of the article;
• feed_name: The name of the feed from which the article originated, as defined in the Pelican config file;

Optional configuration

You can have more control on the generated page, by setting a few more options in your Pelican config file:

• PLANET_MAX_ARTICLES: The maximum number of articles to show on the page.

  By default, all articles from all feeds will be added to the page.

• PLANET_MAX_ARTICLES_PER_FEED: The maximum of articles from a single feed ending on the page.

  By default all articles of a given feed are considered.

• PLANET_MAX_SUMMARY_LENGTH: The maximum number of words kept from the summary.

  By default the summary of the article will be the full text coming from the feed.

RSS feed

Besides the aggregation page, this plugin can write the aggregated articles as an RSS 2.0 feed file, so that your readers can subscribe to your planet:

PLANET_RSS_FILE = 'output/planet.rss.xml'

The feed is only generated when PLANET_RSS_FILE is set. Point it to a file in your Pelican output directory (it is created if it does not exist yet), and it will be published along with the rest of your website.

Each item of the feed carries the article's title, link, summary, author, publication date and, as a category, the name of the feed it comes from. When an article has an image attached, it is added to the item as an enclosure.

The number of items is limited by PLANET_MAX_ARTICLES, just like the aggregation page.

The feed metadata defaults to your Pelican settings, but can be customized:

• PLANET_RSS_TITLE: The title of the feed.

  Defaults to SITENAME.

• PLANET_RSS_LINK: The URL of the website the feed belongs to.

  Defaults to SITEURL.

• PLANET_RSS_DESCRIPTION: The description of the feed.

  Defaults to SITESUBTITLE, or to the title of the feed.

• PLANET_RSS_URL: The public URL of the feed file itself, advertised in the feed as its atom:link rel="self" element.

  By default, no such element is added.

Legalities

pelican-planet is offered under the terms of the GNU Affero General Public License, either version 3 or any later version.

We will never ask you to sign a copyright assignment or any other kind of silly and tedious legal document before accepting your contributions.

In case you're wondering, we do not consider that a website built with pelican-planet would need to be licensed under the AGPL.

Release History

0.26.0

• Generate an RSS feed file with the aggregated articles (#288);
• Use a custom HTTP user agent when fetching the feeds (#269);
• Simplified the imports in the test suite and added a new fixture (#271);

0.25.0

• Handle media:content tags with image attachments (#268);
• Migrated the README from reStructuredText to Markdown (#266);
• Updated the pinned dependencies (pelican, coverage) and the Python version used in CI (#265, #267, #261);

0.24.0

• Publishing to PyPI now uses trusted publishing (#252);
• CI also checks against Python 3.14 (#251);

0.23.0

• Dropped the support for Python 3.7 (#132) and 3.8, added the support for Python 3.12 and 3.13 (#216);
• Handle the exceptions raised when requesting the feeds over HTTP (#133);

0.22.0

• Fixed a TypeError: %d format: a real number is required, not dict raised when logging the statistics;

0.21.0

• Render some additional information when running inside GitHub Actions;

0.20.0

• Print some statistics about the articles and the feeds that were parsed;
• Cleaned up the exceptions handling;

0.19.0

• Use UNIX timestamps when sorting the articles (#115);
• Fixed the check for non 2xx / 3xx HTTP response codes;
• Made the logging of HTTP errors less verbose;

0.18.0

• Skip the articles that raise errors when being parsed and sorted (#114);

0.17.0

• Skip the entries with broken dates when parsing a feed (#113);

0.16.0

• Catch the exceptions raised by make_date() and improve the logging (#111);
• Python 3.7 or later is now required (#79), Python 3.6 is no longer supported;
• CI now runs on Python 3.11 (#112);

0.15.0

• Improved the logging (#30);

0.14.0

• Test fetching the feeds over HTTP (#29);
• Added a code coverage report (#25);
• CI runs black as a separate step and tests Python 3.6 and 3.10 as well;

0.13.0

• Handle the SSL issues when fetching the feeds, with a test case for a site with a broken SSL certificate;

0.12.0

This is a dependencies-only release:

• Updated feedparser to 6.0.6;

0.11.0

• Handle the dates that are not well formatted in RSS feeds (#15);
• Improved the handling of local (file:///) feeds;
• Check the bozo exceptions first when parsing a feed;
• Moved the CI to GitHub Actions and formatted the code with black;

0.10.0

• write_page: generate the links to the blogs and the feeds;
• articles: added a date_iso entry;
• planet.py: expose the list of feeds and add logging;

0.9.1

This is a trivial release, fixing some release-related issues:

• Moved to reStructuredText for the README/CHANGES files, as that's what Pypi prefers;
• Fixed the link to the AGPLv3+ license;
• Added a missing Pypi classifier;
• Added missing files to the dist tarball;

0.9

Initial release:

• Aggregates a list of feeds into a page generated by a template;
• Optionally limits the total number of articles kept, as well as the number of articles per feed;
• Displays the full articles, or just short summaries;
• Supports Python 3.4 and up;