Metadata-Version: 2.4
Name: pelican-feed-planet
Version: 0.25.0
Summary: Blog aggregator plugin for Pelican
Home-page: https://github.com/macbre/pelican-planet
Author: Mathieu Bridon
Author-email: bochecha@daitauha.fr
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: COPYING
Requires-Dist: feedparser==6.0.12
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.

## 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.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;
