Metadata-Version: 2.4
Name: pelican-feed-planet
Version: 0.26.0
Summary: Blog aggregator plugin for Pelican
Home-page: https://github.com/macbre/pelican-planet
Author: Mathieu Bridon, Maciej Brencz
Author-email: bochecha@daitauha.fr, maciej.brencz@gmail.com
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: feedgenerator==2.2.1
Requires-Dist: feedparser==6.0.14
Requires-Dist: Jinja2==3.1.6
Requires-Dist: pelican==4.12.0
Requires-Dist: python-dateutil==2.9.0.post0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Blog aggregation, static-website style!

[![Coverage Status](https://coveralls.io/repos/github/macbre/pelican-feed-planet/badge.svg?branch=master)](https://coveralls.io/github/macbre/pelican-feed-planet?branch=master)

This is a plugin for the [Pelican](https://getpelican.com) 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](http://jinja.pocoo.org/) 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](https://www.gnu.org/licenses/agpl.html).

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;
