Creating plugins for Rootbeer 🔌
Plugins can be very powerful if you know how to use Python
You can make a plugin my creating a folder inside of the plugins/ folder containing a name of your plugin, and adding a file named init.py
Your folder structure should look like this:
.
├── plugins
│ ├── cool_plugin
│ │ └── __init__.py
│ └── __init__.py
The name of the plugin can NOT have any spaces, hyphens, or special characters.
COOL!! Now, let's make a plugin that will generate an HTML file that contains all the pages.
In the plugins/cool_plugin/init.py file, create a function called: gen_html_file_for_all_pages, that takes in a parameter called signal
def gen_html_for_all_pages(signal):
passBut, Rootbeer does not know what to do with the function because we have not told it about it. Well, that's where the cool part comes in.
Rootbeer has a plugin system that will tell Rootbeer when too run the function connected based on the connection name.
Let's import it.
from rootbeer import signals
def gen_html_for_all_pages(sender):
pass
Signals will tell Rootbeer about the functions too run and when. Rootbeer has a list of signals that you can use for your plugins. Here are a list of them and when they run:
before_content_load -- Is ran before the content is loaded.
during_content_load -- Is ran during the content is being loaded.
after_content_load -- Is ran after the content has been loaded.
before_content_render -- Is ran before the content is rendered.
during_content_render -- Is run during the content is being rendered.
after_content_render -- Is ran after the content has been loaded.
before_render_index -- Is ran before the index page is rendered.
during_render_index -- Is ran during the index page is being rendered.
after_render_index -- Is ran after the index page has been rendered.
before_render_archive -- Is ran before the archive page is rendered.
during_render_archive -- Is ran during the archive page is being rendered.
after_render_archive -- Is ran after the archive page has been rendered.To connect a function, all you have to do is to add a decorator above it using this syntax:
@signals.<signal name>.connectabove the function. In our case, we want it too be rendered after the index is finished rendering, because that is just a good place too start. So we will do this:
from rootbeer import signals
@signals.after_render_index.connect
def gen_html_for_all_pages(sender):
passThe function will now be ran after the index page has finished rendering.
Now, too render the page containing all the pages.
The sender parameter contains all the variables needed for rendering pages and more. We can get all the pages we need by simply doing this:
sender.pagesIt will give us a list of pages to use.
To render our custom page, we can use the environment provided from sender.
from rootbeer import signals
@signals.after_render_index.connect
def gen_html_for_all_pages(sender):
# This will get the template from the themes dir.
template = sender.env.get_template('custom_page.html')
# This will create the new file if it does not exist
with open(f'{sender.out_dir}/custom_page.html', 'w') as file:
file.write(
template.render(
all_pages=sender.pages
)
)now, we need too create the template in the theme directory. So create: 'custom_page.html' in the theme's directory.
Paste this into the template's directory:
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Title</title>
</head>
<body>
{# This will loop through all the pages Rootbeer has parsed #}
{% for page in all_pages %}
{# This will get the title of the page. #}
{{ page.metadata.title }}
{% endfor %}
</body>
</html>and finally, we need too actually tell Rootbeer we are using the plugin. In the config file, add this piece of code:
plugins:
- cool_pluginand when you run Rootbeer, you should now see a new page in the public/ folder that contains all the pages' titles. EPICCCCCC
