# Webring
[](https://github.com/pelican-plugins/webring/actions)
[](https://pypi.org/project/pelican-webring/)
This Pelican plugin adds a webring or feed aggregation to your site from a list
of web feeds.
It retrieves the latest posts from a list of web feeds and makes them available
in templates, effectively creating a [partial webring][1] or feed aggregation.
Posts are sorted from newer to older.
It is inspired by [openring](https://git.sr.ht/~sircmpwn/openring), a tool for
generating an HTML file to include in your [SSG][2] from a template and a list
of web feeds, and
[pelican-planet](https://framagit.org/bochecha/pelican-planet), a Pelican
plugin for creating feed aggregations.
Installation
------------
This plugin can be installed via:
python -m pip install pelican-webring
Settings
--------
```
WEBRING_FEED_URLS = []
```
A list of web feeds in the form of a URL or local file.
```
WEBRING_MAX_ARTICLES = 3
```
The maximum number of articles.
```
WEBRING_ARTICLES_PER_FEED = 1
```
The maximum number of articles per feed.
```
WEBRING_SUMMARY_WORDS = 20
```
The maximum number of words of post summaries. If set to 0, truncation is
disabled.
```
WEBRING_CLEAN_SUMMARY_HTML = True
```
Whether to clean html tags from post summaries or not.
**Example**
Let's suppose we have two blogs in our webring and want to show two articles
per blog. We would also like to show a quite short summary.
```
WEBRING_FEED_URLS = [
'https://justinmayer.com/feeds/all.atom.xml',
'https://danluu.com/atom.xml'
]
WEBRING_ARTICLES_PER_FEED = 2
WEBRING_MAX_ARTICLES = 4
WEBRING_SUMMARY_LENGTH = 25
```
Templates
---------
The plugin makes available the resulting web feed articles in the variable
`webring_articles`.
All existing _date_ attributes are Pelican `utils.SafeDatetime` objects, which
can be used with [Pelican's Jinja filter
`strftime`](https://docs.getpelican.com/en/stable/themes.html#date-formatting).
Each article contains all available properties in the original feed entry, for
example:
- `article.title`: The article title.
- `article.link`: The article URL.
- `article.date`: The article date as a Pelican `utils.SafeDatetime` object.
- `article.summary`: The article summary, as provided in the web feed and modified
according to this plugin's settings.
- `article.description`: The original article summary, without cleaning or
truncation.
Articles also contain information about the _source feed_, which can be
accessed through `source_` prefixed attributes:
- `source_title`: The title of the web feed.
- `source_link`: A link to the web feed.
- `source_id`: An identification field provided in some web feeds.
If you access an attribute that is not present in the entry or source feed, an
empty string will be returned, except for _dates_ (`published`, `updated`,
`created` and `expired`) that `None` is returned.
For a list of available entry and source feed attributes, [read the feedparser
reference document](https://pythonhosted.org/feedparser/reference.html).
You can use `webring_articles` in any kind of content type, including _pages_
and _articles_. Read the following sections for examples on how to use this
variable in your templates.
### Adding a Webring section in the bottom of articles
Imagine we'd like to put our webring in the bottom of articles, using the
default Pelican template (ie. notmyidea). To simplify, we'll use the existing
CSS classes.
Edit the `notmyidea/templates/base.html` file and make it look like this:
```
...
<section id="extras" class="body">
{% if WEBRING_FEED_URLS %}
<div class="webring">
<h2>Webring</h2>
{% for article in webring_articles %}
<p><a href="{{ article.link }}">{{ article.title }}</a></p>
<p>{{ article.date|strftime('%d %B %Y') }} - {{ article.summary}}</p>
{% endfor %}
</div>
{% endif %}
{% if LINKS %}
...
```
If there were no links or social widgets, the result would be like in the
image below:
### Adding a feed aggregation page
In this case, we'd like to generate a new page with all feed contents processed
by this plugin. For example, imagine we'd like to access that page as:
`https://my-domain.com/feed-aggregation`.
This objective can be accomplished in several ways in Pelican. We're showing
here one that only requires a new HTML template.
The following is an example template file named `feed-aggregation.html` based on
`page.html` that should reside in your theme template directory:
```
{% extends "base.html" %}
{% block title %}Feed aggregation{% endblock %}
{% block content %}
<section id="content" class="body">
<h1 class="entry-title">Feed aggregation</h1>
{% if WEBRING_FEED_URLS %}
{% for article in webring_articles %}
<article class="hentry">
<header>
<h2><a href="{{ article.link }}">{{ article.title }}</a></h2>
</header>
<p>{{ article.date|strftime('%d %B %Y') }}</p>
<div class="entry-content">
{{ article.summary}}
</div>
</article>
{% endfor %}
{% endif %}
</section>
{% endblock %}
```
Finally, in order for our template to be rendered in the wanted location, we add the following **template page** to our `pelicanconf.py`. Note that `feed-aggregation.html` is relative to your theme's template directory.
```
TEMPLATE_PAGES = { 'feed-aggregation.html': 'feed-aggregation/index.html' }
```
The final result would be as in the image below:
Contributing
------------
Contributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].
To start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.
[existing issues]: https://github.com/pelican-plugins/webring/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
[1]: https://en.wikipedia.org/wiki/Webring "In a proper webring, websites would be linked in a circular structure."
[2]: https://en.wikipedia.org/wiki/Category:Static_website_generators "Static Site Generator"
Raw data
{
"_id": null,
"home_page": "https://github.com/pelican-plugins/webring",
"name": "pelican-webring",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "pelican,plugin",
"author": "David Alfonso",
"author_email": "developer@davidalfonso.es",
"download_url": "https://files.pythonhosted.org/packages/b5/da/c319b97e6e11d5db6c6aead675daaea4edd8c50aa20f2604094f1781f018/pelican_webring-1.4.0.tar.gz",
"platform": null,
"description": "# Webring\n\n[](https://github.com/pelican-plugins/webring/actions)\n[](https://pypi.org/project/pelican-webring/)\n\nThis Pelican plugin adds a webring or feed aggregation to your site from a list\nof web feeds.\n\nIt retrieves the latest posts from a list of web feeds and makes them available\nin templates, effectively creating a [partial webring][1] or feed aggregation.\nPosts are sorted from newer to older.\n\nIt is inspired by [openring](https://git.sr.ht/~sircmpwn/openring), a tool for\ngenerating an HTML file to include in your [SSG][2] from a template and a list\nof web feeds, and\n[pelican-planet](https://framagit.org/bochecha/pelican-planet), a Pelican\nplugin for creating feed aggregations.\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n python -m pip install pelican-webring\n\nSettings\n--------\n\n```\nWEBRING_FEED_URLS = []\n```\nA list of web feeds in the form of a URL or local file.\n\n```\nWEBRING_MAX_ARTICLES = 3\n```\nThe maximum number of articles.\n\n```\nWEBRING_ARTICLES_PER_FEED = 1\n```\nThe maximum number of articles per feed.\n\n```\nWEBRING_SUMMARY_WORDS = 20\n```\nThe maximum number of words of post summaries. If set to 0, truncation is\ndisabled.\n\n```\nWEBRING_CLEAN_SUMMARY_HTML = True\n```\nWhether to clean html tags from post summaries or not.\n\n**Example**\n\nLet's suppose we have two blogs in our webring and want to show two articles\nper blog. We would also like to show a quite short summary.\n\n```\nWEBRING_FEED_URLS = [\n 'https://justinmayer.com/feeds/all.atom.xml',\n 'https://danluu.com/atom.xml'\n]\nWEBRING_ARTICLES_PER_FEED = 2\nWEBRING_MAX_ARTICLES = 4\nWEBRING_SUMMARY_LENGTH = 25\n```\n\nTemplates\n---------\n\nThe plugin makes available the resulting web feed articles in the variable\n`webring_articles`.\n\nAll existing _date_ attributes are Pelican `utils.SafeDatetime` objects, which\ncan be used with [Pelican's Jinja filter\n`strftime`](https://docs.getpelican.com/en/stable/themes.html#date-formatting).\n\nEach article contains all available properties in the original feed entry, for\nexample:\n\n- `article.title`: The article title.\n- `article.link`: The article URL.\n- `article.date`: The article date as a Pelican `utils.SafeDatetime` object.\n- `article.summary`: The article summary, as provided in the web feed and modified\naccording to this plugin's settings.\n- `article.description`: The original article summary, without cleaning or\n truncation.\n\nArticles also contain information about the _source feed_, which can be\naccessed through `source_` prefixed attributes:\n\n- `source_title`: The title of the web feed.\n- `source_link`: A link to the web feed.\n- `source_id`: An identification field provided in some web feeds.\n\nIf you access an attribute that is not present in the entry or source feed, an\nempty string will be returned, except for _dates_ (`published`, `updated`,\n`created` and `expired`) that `None` is returned.\n\nFor a list of available entry and source feed attributes, [read the feedparser\nreference document](https://pythonhosted.org/feedparser/reference.html).\n\nYou can use `webring_articles` in any kind of content type, including _pages_\nand _articles_. Read the following sections for examples on how to use this\nvariable in your templates.\n\n### Adding a Webring section in the bottom of articles\n\nImagine we'd like to put our webring in the bottom of articles, using the\ndefault Pelican template (ie. notmyidea). To simplify, we'll use the existing\nCSS classes.\n\nEdit the `notmyidea/templates/base.html` file and make it look like this:\n\n```\n ...\n <section id=\"extras\" class=\"body\">\n {% if WEBRING_FEED_URLS %}\n <div class=\"webring\">\n <h2>Webring</h2>\n {% for article in webring_articles %}\n <p><a href=\"{{ article.link }}\">{{ article.title }}</a></p>\n <p>{{ article.date|strftime('%d %B %Y') }} - {{ article.summary}}</p>\n {% endfor %}\n </div>\n {% endif %}\n {% if LINKS %}\n ...\n```\n\nIf there were no links or social widgets, the result would be like in the\nimage below:\n\n\n\n### Adding a feed aggregation page\n\nIn this case, we'd like to generate a new page with all feed contents processed\nby this plugin. For example, imagine we'd like to access that page as:\n`https://my-domain.com/feed-aggregation`.\n\nThis objective can be accomplished in several ways in Pelican. We're showing\nhere one that only requires a new HTML template.\n\nThe following is an example template file named `feed-aggregation.html` based on\n`page.html` that should reside in your theme template directory:\n\n```\n{% extends \"base.html\" %}\n{% block title %}Feed aggregation{% endblock %}\n\n{% block content %}\n<section id=\"content\" class=\"body\">\n <h1 class=\"entry-title\">Feed aggregation</h1>\n\n {% if WEBRING_FEED_URLS %}\n {% for article in webring_articles %}\n <article class=\"hentry\">\n <header>\n <h2><a href=\"{{ article.link }}\">{{ article.title }}</a></h2>\n </header>\n <p>{{ article.date|strftime('%d %B %Y') }}</p>\n <div class=\"entry-content\">\n {{ article.summary}}\n </div>\n </article>\n {% endfor %}\n {% endif %}\n\n</section>\n{% endblock %}\n```\n\nFinally, in order for our template to be rendered in the wanted location, we add the following **template page** to our `pelicanconf.py`. Note that `feed-aggregation.html` is relative to your theme's template directory.\n\n```\nTEMPLATE_PAGES = { 'feed-aggregation.html': 'feed-aggregation/index.html' }\n```\n\nThe final result would be as in the image below:\n\n\n\nContributing\n------------\n\nContributions are welcome and much appreciated. Every little bit helps. You can contribute by improving the documentation, adding missing features, and fixing bugs. You can also help out by reviewing and commenting on [existing issues][].\n\nTo start contributing to this plugin, review the [Contributing to Pelican][] documentation, beginning with the **Contributing Code** section.\n\n[existing issues]: https://github.com/pelican-plugins/webring/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n[1]: https://en.wikipedia.org/wiki/Webring \"In a proper webring, websites would be linked in a circular structure.\"\n[2]: https://en.wikipedia.org/wiki/Category:Static_website_generators \"Static Site Generator\"\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Adds a webring to your site from a list of web feeds",
"version": "1.4.0",
"split_keywords": [
"pelican",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "30fa902a3e303cf69f3483ac7076011a21a3f004ef190f54e748195b15c1fded",
"md5": "438ba95457d3f3a8f9be9a2a03b24799",
"sha256": "e60bba7f2e314b069ab6bd5d3730b113c3bfd10f402fb89a506a144dec7e3e71"
},
"downloads": -1,
"filename": "pelican_webring-1.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "438ba95457d3f3a8f9be9a2a03b24799",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 24761,
"upload_time": "2023-01-27T16:34:36",
"upload_time_iso_8601": "2023-01-27T16:34:36.471569Z",
"url": "https://files.pythonhosted.org/packages/30/fa/902a3e303cf69f3483ac7076011a21a3f004ef190f54e748195b15c1fded/pelican_webring-1.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b5dac319b97e6e11d5db6c6aead675daaea4edd8c50aa20f2604094f1781f018",
"md5": "8c0de8657483847f3620974d2619c2a6",
"sha256": "68518bd264d875e6eccc5fc97422069efed7944fab4a00a4a03f932804614940"
},
"downloads": -1,
"filename": "pelican_webring-1.4.0.tar.gz",
"has_sig": false,
"md5_digest": "8c0de8657483847f3620974d2619c2a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 25903,
"upload_time": "2023-01-27T16:34:38",
"upload_time_iso_8601": "2023-01-27T16:34:38.113639Z",
"url": "https://files.pythonhosted.org/packages/b5/da/c319b97e6e11d5db6c6aead675daaea4edd8c50aa20f2604094f1781f018/pelican_webring-1.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-27 16:34:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "pelican-plugins",
"github_project": "webring",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pelican-webring"
}
JSON
