This is a plugin pack for the render-engine
static site generator. It currently includes the
following plugins:
To install just run:
pip install re-plugin-pack
Once installed you can access the plugins by importing re_plugin_pack
:
import re_plugin_pack
from re_plugin_pack import <plugin>
This plugin will add a list of the latest entries for one or more Collection
s to a given Page
.
It can be configured at the Page or Site
levels and can be configured to provide the latest entries
for any number of Collection
s. The entries used are in the sort order as defined in the Collection
object.
The plugin has the following default settings:
{
"collection": ["url"],
"entries": ["title", "url"],
"pages": ["index"],
"max_entries": 3,
}
collection
- a list of attributes to include for the collection.entries
- a list of attributes to include for a given entry.pages
- a list of pages to add theCOLLECTIONS
entry to it'stemplate_vars
(Only needed when running as aSite
plugin)max_entries
- The maximum number of entries to include for a collection. The default is 3.-1
indicates that all entries should be populated.
In addition to the default settings entries can be added for each Collection
defining how many
entries it should include:
- Positive integer - Include up to the number specified entries. For example:
'Collection1': 5
will include the 5 latest entries in thetemplate_vars
. 0
- Exclude this collection. For example:'Collection2': 0
will not includeCollection2
in thetemplate_vars
.- Negative integer - Include all entries. For example:
'Collection3': -1
will include all entries forCollection3
in thetemplate_vars
To configure at the Page
level just include (LatestEntris, <settings_dict)
in the plugins
attribute when declaring the Page
. If no settings overrides are needed, include LatestEntries
by itself in the plugin
attribute.
Example:
from render_engine import Site, Page
from re-plugin-pack import LatestEntries
app = Site()
@app.page
class MyPage(Page):
plugins = [
(
LatestEntries,
{
"Collection1": 5, # Include the 5 most recent entries
"Collection2": 0, # Exclude this collection
"Collection3": -1, # Include all entries in the collection
},
)
]
...
To configure at the Site
level call app.register_plugins(LatestEntries, LatestEntries=<settings>)
if settings overrides are being used. To configure without additional settings, call
app.register_plugin(LatestEntries)
.
Example:
from render_engine import Site, Page
from re-plugin-pack import LatestEntries
app = Site()
# The following will use the default settings overriding the pages to run on to be page1 and page2
app.register_plugins(LatestEntries, LatestEntries={'pages': ['page1', 'page2']})
# The following will only enable for the Blog collection:
app.register_plugins(LatestEntries, LatestEntries={'max_entries': 0, 'Blog': 3})
NOTE: If configuring at the Site
level the registration should be done after adding all
Page
entries to the Site
. When adding a Page
to a Site
all plugins registered to the
Site
are automatically registered to the new Page
object.
The latest entries will be added to the COLLECTIONS
key of the template_vars
for the Page
and can be accessed in the template as COLLECTIONS
.
Example template implementation:
{% for collection, collection_data in COLLECTIONS.items() %}
Most recent <a href="{{ collection_data['url'] }}">{{ collection }}</a> entries:
<ul>
{% for entry in collection_data['entries'] %}
<li><a href="{{ entry['url'] }}">{{ entry['title'] }}</a></li>
{% endfor %}
</ul>
{% endfor %}
This plugin will give each page in a Collection
access to certain attributes of the next and
previous pages in the collection. By default, only the URL and title of those pages will be
made available, however additional attributes may also be requested via the settings. If an
attributes is in the list to include but does not exist in the page(s) None
will be used.
This plugin runs at the Collection
level and can be registered at the Site
or Collection
level.
This plugin has no default settings. If you wish to add additional attributes, include in the
registration a settings dictionary with a key of additional_attributes
having a list of
attributes as its value.
To configure at the Site
level call app.register_plugins(NextPrevPlugin, NextPrevPlugin=<settings>)
if settings overrides are being used. To configure without additional settings, call
app.register_plugin(NextPrevPlugin)
.
Example:
from render_engine import Site, Page
from re-plugin-pack import NextPrevPlugin
app = Site()
# The following will include the date attribute in in the data made available.
app.register_plugins(NextPrevPlugin, NextPrevPlugin={'additional_attributes': ['date']})
# The following will not include any additional attributes
app.register_plugins(NextPrevPlugin)
NOTE: If configuring at the Site
level the registration should be done after adding all
Collection
entries to the Site
. When adding a Collection
to a Site
all plugins
registered to the Site
are automatically registered to the new Collection
object.
To configure at the Page
level just include (NextPrevPlugin, <settings_dict)
in the plugins
attribute when declaring the Collection
. If no settings overrides are needed, include
NextPrevPlugin
by itself in the plugin
attribute.
Example:
from render_engine import Site, Page
from re-plugin-pack import NextPrevPlugin
app = Site()
@app.page
class MyPage(Page):
plugins = [
(
NextPrevPlugin,
{
'additional_attributes': [ # This will make the date and description attributes available
'date',
'description',
]
},
)
]
...
When run this plugin will add a dictionary with the requested data to the template_vars
of
each page in the Collection
. The dictionary added looks like:
{
'collection_url': <url>,
'collection_title': <title>,
'next_url': <url>,
'next_title': <title>,
'prev_url': <url>,
'prev_title': <title>,
}
If additional_attributes
are included in the settings, they will be in the dictionary as:
prev_<attr>: <value>
and next_<attr>: <value>
.
{% if prev_url %}
<span class="prev_data">
Previous: <a href="{{ prev_url }}">{{ prev_title }}</a>
</span>
{% endif %}
{% if next_url %}
<span class="next_data">
Next: <a href="{{ next_url }}">{{ next_title }}</a>
</span>
{% endif %}
This is a plugin that will skip pages in a Collection
that are marked as draft
. This allows
you to have WIP posts and still make changes to other things without publishing things that are
not ready to be posted.
The Drafts
plugin has a single setting:
{
'show_drafts': True,
}
When show_drafts
is set to False
the plugin will run, prior to rendering the Collection
and remove all pages in the collection that have a True
value for the draft
attribute will
not be rendered when building the site. This plugin runs at the Collection
level and can be
registered either Site
-wide or for individual collections.
NOTE: Plugins run in the reverse order of registration. If you are using both this and
NextPrevPlugin
make sure that you register NextPrevPlugin
(or any similar
plugin) before you register Drafts
or you might have unexpected results as pages that were
processed will have been removed.
In order to have this work effectively, so that you can see the draft posts locally when you
use render-engine serve
, you will need to differentiate between the environments. To
accomplish this you can use an environment variable and add this line of code into your
app.py
:
import os
ENABLE_DRAFTS = {"show_drafts": os.environ.get("SHOW_DRAFTS", False)}
When you register the plugin make sure to include the ENABLE_DRAFTS
as the settings
for the plugin:
import os
from re_plugin_pack import Drafts
from render_engine import Site, Collection
ENABLE_DRAFTS = {"show_drafts": os.environ.get("SHOW_DRAFTS", False)}app=Site()
# Either at the `Site` level:
app.register_plugins(Drafts, Drafts=ENABLE_DRAFTS)
# Or at the `Collection` level:
@app.collection
class MyCollection(Collection):
plugins=[(Drafts, ENABLE_DRAFTS)]
...
Make sure that you register plugins in the order that you want them to run. Remember that
any plugin that is registered with the Site
prior to creating the Collection
is included
in the Collection
the will have been registered first and will run after plugins that
are registered at the Collection
level. Since plugins are invoked in the reverse order
of registration Drafts
should be the last plugin run for a Collection
.
Example registration:
import os
from re_plugin_pack import Drafts, NextPrevPlugin
from render_engine import Site, Collection
ENABLE_DRAFTS = {"show_drafts": os.environ.get("SHOW_DRAFTS", False)}app=Site()
@app.collection
class MyCollection(Collection):
plugins = [
NextPrevPlugin,
(Drafts, ENABLE_DRAFTS),
]
The above order will run the Drafts
plugin first on that collection.
To mark a post as a draft
just add a truthy value for the draft
attribute to the content:
---
title: WIP Post
date: 2025-06-01T02:49:18
draft: Yes
---
This is a draft post
The goal of this plugin is to normalize entries in the date
attribute of pages. This is necessary
since valid entries include datetime.date
, datetime.datetime
, and date like strings. Since
inconsistencies in the values of these fields can cause issues with sorting:
TypeError: '<' not supported between instances of 'datetime.datetime' and 'datetime.date'
and rendering if using the format_datetime
function it is important that the date-like objects
be normalized into datetime.datetime
objects regardless of how they are set.
DateNormalizer
has no settings.
DateNormalizer
is a Site
level plugins that runs prior to the site being rendered. It must
be registered at the site level:
from render_engine import Site, Page
from re-plugin-pack import DateNormalizer
app = Site()
app.register_plugins(DateNormalizer)