Series: A Plugin for Pelican
============================
[](https://github.com/pelican-plugins/series/actions)
[](https://pypi.org/project/pelican-series/)
Series is a Pelican plugin that joins multiple posts into a series. Globally, it provides a list of all the series, and for each article it provides a list of all articles in the same series and links to the next and previous articles in the series.
Installation
------------
This plugin can be installed via:
python -m pip install pelican-series
As long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `series` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.
Usage
-----
In order to mark reStructuredText-formatted posts as part of a series, use the `:series:` metadata:
:series: NAME_OF_THIS_SERIES
Or, for Markdown-formatted content:
Series: NAME_OF_THIS_SERIES
The plugin collects all articles or pages belonging to the same series and provides series-related variables that you can use in your template.
Articles and pages
------------------
This plugin works both with articles and pages. As Pelican uses the specific variable `article` for article templates and `page` for page templates it is complicated to give examples that work for both cases. In the following documentation all example will mention `article.` (e.g. `article.series`, `article.title`) but the code works in the same way with `page` (e.g. `page.series`, `page.title`).
Article series and page series are created separately, so even if an article and a page have the same series they won't appear together.
Indexing
--------
By default, articles in a series are ordered by date and then automatically numbered. Pages in a series are ordered by title and automatically numbered.
If you want to force a given order, specify `:series_index:` (reST) or `series_index:` (Markdown) in the article metadata, starting from 1. All articles with this enforced index are put at the beginning of the series and ordered according to the index itself. All the remaining articles come after them, ordered with the default ordering (date for articles and title for pages).
The plugin provides the following variables to your templates:
* `article.series.name` is the name of the series as specified in the article metadata
* `article.series.index` is the index of the current article inside the series
* `article.series.all` is an ordered list of all articles in the series (including the current one)
* `article.series.all_previous` is an ordered list of the articles published before the current one
* `article.series.all_next` is an ordered list of the articles published after the current one
* `article.series.previous` is the previous article in the series (a shortcut to `article.series.all_previous[-1]`) or `None` for the first article
* `article.series.next` is the next article in the series (a shortcut to `article.series.all_next[0]`) or `None` for the last one
For example:
```html+jinja
{% if article.series %}
<p>This post is part {{ article.series.index }} of the "{{ article.series.name }}" series:</p>
<ol class="parts">
{% for part_article in article.series.all %}
<li {% if part_article == article %}class="active"{% endif %}>
<a href='{{ SITEURL }}/{{ part_article.url }}'>{{ part_article.title }}</a>
</li>
{% endfor %}
</ol>
{% endif %}
```
Global Context
--------------
**Warning**: in version 3 the global key `series` has been renamed to `article_series` to differentiate it from the new global key `page_series`.
The plugin also adds the keys `article_series` and `page_series` to the global context. They are dictionaries of all series names (as keys) and items (as values). You can use that to list all the series in your site, for example
```html+jinja
{% for series_name, series_articles in series.items() %}
{% set article = series_articles[0] %}
<article class="card">
<a href="{{ article.url }}" class="image">
<img src="/images/{{ article.image }}.jpg" alt="{{ article.image }}" />
</a>
<div class="card-body">
<a href="{{ article.url }}"><h3 class="card-title">{{ series_name }}</h3></a>
<ul class="actions">
<li><a href="{{ article.url }}" class="button">Start</a></li>
</ul>
</div>
</article>
{% endfor %}
```
As it is not possible to create pages from plugins you can leverage it to create a page for a specific series, even though you have to hard code the name of the series in the template.
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/series/issues
[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html
License
-------
This project is licensed under the AGPL 3.0 license.
Raw data
{
"_id": null,
"home_page": "https://github.com/pelican-plugins/series",
"name": "pelican-series",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8.1",
"maintainer_email": null,
"keywords": "pelican, plugin, series, multiple",
"author": "Leonardo Giordani",
"author_email": "giordani.leonardo@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/44/13/bc65ef34fbb921a8a0c56f4fc77b33fd0ebf1e8e989ef2fa24ce42e9453b/pelican_series-3.0.0.tar.gz",
"platform": null,
"description": "Series: A Plugin for Pelican\n============================\n\n[](https://github.com/pelican-plugins/series/actions)\n[](https://pypi.org/project/pelican-series/)\n\n\nSeries is a Pelican plugin that joins multiple posts into a series. Globally, it provides a list of all the series, and for each article it provides a list of all articles in the same series and links to the next and previous articles in the series.\n\nInstallation\n------------\n\nThis plugin can be installed via:\n\n python -m pip install pelican-series\n\nAs long as you have not explicitly added a `PLUGINS` setting to your Pelican settings file, then the newly-installed plugin should be automatically detected and enabled. Otherwise, you must add `series` to your existing `PLUGINS` list. For more information, please see the [How to Use Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins) documentation.\n\nUsage\n-----\n\nIn order to mark reStructuredText-formatted posts as part of a series, use the `:series:` metadata:\n\n :series: NAME_OF_THIS_SERIES\n\nOr, for Markdown-formatted content:\n\n Series: NAME_OF_THIS_SERIES\n\nThe plugin collects all articles or pages belonging to the same series and provides series-related variables that you can use in your template.\n\nArticles and pages\n------------------\n\nThis plugin works both with articles and pages. As Pelican uses the specific variable `article` for article templates and `page` for page templates it is complicated to give examples that work for both cases. In the following documentation all example will mention `article.` (e.g. `article.series`, `article.title`) but the code works in the same way with `page` (e.g. `page.series`, `page.title`).\n\nArticle series and page series are created separately, so even if an article and a page have the same series they won't appear together.\n\nIndexing\n--------\n\nBy default, articles in a series are ordered by date and then automatically numbered. Pages in a series are ordered by title and automatically numbered.\n\nIf you want to force a given order, specify `:series_index:` (reST) or `series_index:` (Markdown) in the article metadata, starting from 1. All articles with this enforced index are put at the beginning of the series and ordered according to the index itself. All the remaining articles come after them, ordered with the default ordering (date for articles and title for pages).\n\nThe plugin provides the following variables to your templates:\n\n* `article.series.name` is the name of the series as specified in the article metadata\n* `article.series.index` is the index of the current article inside the series\n* `article.series.all` is an ordered list of all articles in the series (including the current one)\n* `article.series.all_previous` is an ordered list of the articles published before the current one\n* `article.series.all_next` is an ordered list of the articles published after the current one\n* `article.series.previous` is the previous article in the series (a shortcut to `article.series.all_previous[-1]`) or `None` for the first article\n* `article.series.next` is the next article in the series (a shortcut to `article.series.all_next[0]`) or `None` for the last one\n\nFor example:\n\n```html+jinja\n{% if article.series %}\n <p>This post is part {{ article.series.index }} of the \"{{ article.series.name }}\" series:</p>\n <ol class=\"parts\">\n {% for part_article in article.series.all %}\n <li {% if part_article == article %}class=\"active\"{% endif %}>\n <a href='{{ SITEURL }}/{{ part_article.url }}'>{{ part_article.title }}</a>\n </li>\n {% endfor %}\n </ol>\n{% endif %}\n```\n\nGlobal Context\n--------------\n\n**Warning**: in version 3 the global key `series` has been renamed to `article_series` to differentiate it from the new global key `page_series`.\n\nThe plugin also adds the keys `article_series` and `page_series` to the global context. They are dictionaries of all series names (as keys) and items (as values). You can use that to list all the series in your site, for example\n\n```html+jinja\n{% for series_name, series_articles in series.items() %}\n{% set article = series_articles[0] %}\n<article class=\"card\">\n\t<a href=\"{{ article.url }}\" class=\"image\">\n\t\t<img src=\"/images/{{ article.image }}.jpg\" alt=\"{{ article.image }}\" />\n\t</a>\n\t<div class=\"card-body\">\n \t<a href=\"{{ article.url }}\"><h3 class=\"card-title\">{{ series_name }}</h3></a>\n \t<ul class=\"actions\">\n \t\t<li><a href=\"{{ article.url }}\" class=\"button\">Start</a></li>\n \t</ul>\n\t</div>\n</article>\n{% endfor %}\n```\n\nAs it is not possible to create pages from plugins you can leverage it to create a page for a specific series, even though you have to hard code the name of the series in the template.\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/series/issues\n[Contributing to Pelican]: https://docs.getpelican.com/en/latest/contribute.html\n\nLicense\n-------\n\nThis project is licensed under the AGPL 3.0 license.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Series is a Pelican plugin that joins multiple posts into a series",
"version": "3.0.0",
"project_urls": {
"Documentation": "https://docs.getpelican.com",
"Funding": "https://donate.getpelican.com/",
"Homepage": "https://github.com/pelican-plugins/series",
"Issue Tracker": "https://github.com/pelican-plugins/series/issues",
"Repository": "https://github.com/pelican-plugins/series"
},
"split_keywords": [
"pelican",
" plugin",
" series",
" multiple"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73d107daf1c643cc090f15641e8160bd7e5a8687cb6f71b121f789069829b154",
"md5": "dbd08e62fcc6b8082b4dd57013fb5581",
"sha256": "dc6cd93690afeb5336d867e702070396ca0a465fba1976083281e01a346ed882"
},
"downloads": -1,
"filename": "pelican_series-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dbd08e62fcc6b8082b4dd57013fb5581",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8.1",
"size": 10842,
"upload_time": "2024-04-29T10:40:48",
"upload_time_iso_8601": "2024-04-29T10:40:48.833299Z",
"url": "https://files.pythonhosted.org/packages/73/d1/07daf1c643cc090f15641e8160bd7e5a8687cb6f71b121f789069829b154/pelican_series-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4413bc65ef34fbb921a8a0c56f4fc77b33fd0ebf1e8e989ef2fa24ce42e9453b",
"md5": "d51e2484050c5d56e2d263fde5cee746",
"sha256": "e44ced55b8f1459b02392a55c77f19d3e449f75cf120d5b1de6705819781e3f3"
},
"downloads": -1,
"filename": "pelican_series-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "d51e2484050c5d56e2d263fde5cee746",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8.1",
"size": 8205,
"upload_time": "2024-04-29T10:40:50",
"upload_time_iso_8601": "2024-04-29T10:40:50.954351Z",
"url": "https://files.pythonhosted.org/packages/44/13/bc65ef34fbb921a8a0c56f4fc77b33fd0ebf1e8e989ef2fa24ce42e9453b/pelican_series-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-29 10:40:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pelican-plugins",
"github_project": "series",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pelican-series"
}
JSON
