Skip to content

Plugin Development

Jump to bottom
Egbert edited this page Jul 1, 2024 · 24 revisions

Welcome to Pelican Plugin Development!

Let's get the non-production environment setup out of the way so that plugin development starts right away. When I say non-production, I meant nothing gets installed, and no Python virtual environment required.

Your Plugin Repository

To better save all your coding efforts (and mishaps), create a Git repository. You could do git init inside your own myplugin directory. Or you could do it like I do, leverage Github 'create repository' and clone it into your development area on your platform.

cd ~
cd work
# Substitute 'my_plugin' with the actual plugin name
gh repo clone <your-github-username>/my_plugin
cd my_plugin
mkdir pelican pelican/plugins pelican/plugins/my_plugin

There. Now all your works can be saved (or perhaps mostly backtracked into a sane state, as I do).

Development Area

Pelican Repository

We are not making much changes, if at all, toward Pelican itself. Just clone the repository.

NOTE: we have an optional 1-liner change in Pelican to greatly assist in prototyping/debugging plugins.

cd ~
cd work
git clone https://github.com/getpelican/pelican

A pelican repository has been installed into a newly created pelican directory.

Plugins Repository

Separately, Pelican has a single repository for all its plugins; many plugins are essentially a simple link to OTHERS' repository.

Obtain the pelican plugins by executing:

cd ~
cd work
git clone https://github.com/getpelican/pelican-plugins

A pelican-plugins repository has been cloned into your newly created pelican-plugins directory. We will almost never make any changes to it. However, some of us plugin developers are dependent on other plugins, hence ... this repo.

Our Very Own Website

Now for that "website", your static site-generated (SSG) website, we have a choice of where to put this website content:

  • A separate directory (away from pelican and pelican-plugins) (a very common choice)
  • Hijack (reuse) the pelican repository

Ideally, your actual SSG website would be in a directory of its own.

But this in here is rapid prototyping, we will do very little in the way of doing the HTML webmastering nor CSS page-layout work. Instead, we make the content directory right there inside your very own pelican repo (and throw it away upon completion, or worse, move it to your future plugin repo).

Create a website having no font, no image, no template, no support, no extra; a nice simple web site that our brand new plugin can focus entire on and process your content files.

cd ~/work/pelican
# `git pelican` already created the pelican/plugins
mkdir content content/articles content/pages output plugins/myplugin

A Nice Configuration File

Go to the pelican directory:

cd ~/work/pelican

Populate your pelican executable file:

Since the rollout of invoke by some Python developer, many development environments were impeded and hindered because pelican executable is now gone. We need to put that back in for rapid-prototyping:

Add an executable file in the pelican/pelican directory (ya, the executable will be pelican/pelican/pelican).

#!/usr/bin/env python
# -*- coding: utf-8 -*-
import re
import sys
import logging
from pelican.__main__ import main
if __name__ == "__main__":
    sys.argv[0] = re.sub(r"(-script\.pyw|\.exe)?$", "", sys.argv[0])
    sys.exit(main())

Pelican Configuration Settings File

Lastly before running pelican, seed your pelicanconf.py with:

DEBUG = True
PATH = 'content'   # our newly created location for our articles/pages to reside in/under
OUTPUT_PATH = 'output'
ARTICLES_PATH = ['articles']
PLUGIN_PATHS = [ '~/work/pelican/plugins', '~/work/pelican-plugins', '~/work/my_plugin/pelican/plugins' ]
PLUGINS = [
        'my_plugin'
        ]
AUTHOR = 'John'
SITENAME = 'My 1st Site'
# for 
PORT = 8000
BIND = '127.0.0.1'

A Make To Rule Them All

Copy the Makefile from pelican/docs up to pelican

cd ~/work/pelican
cp docs/Makefile Makefile

The make utility now can tell you what you can do with this Makefile:

$ make help

Our tight, iterative, develop, run, redevelop, redevelop

$ make
$ make serve

Development Setups

Console Development

Dual-Console Development

In a dual-console development, one terminal is always doing make serve and is minimized.

Other console is for your rapid prototype; your edit/make-html/edit/make-html, you then view your handiwork using a web browser using a Refresh button, Ctrl-F5 (Firefox) for cache-busting refresh of your targeted page view.

Triple-Console Development

In the three-console development, the consoles are used for:

  • make serve, like always; no need to restart them
  • vi my_plugin.py always, never exited, occasionally saving
  • auto-execute-pelican.sh, my very own personal script

This auto-execute-pelican.sh script will always fire a Pelican session after your editor saves the file, (it is never too soon to execute Pelican, fire away!)

#!/bin/sh
while inotifywait -mre create,delete,modify /home;do
    ./penguin -v -v -v -v -d 
done

TIP: Your Firefox web browser could be automatically set to refresh the same page in the same tab using this 'Auto-Refresh' Add-On.

Integrated Development Environment (IDE)

PyCharm (JetBrains)

VSCode (Microsoft)

Emacs (UNIX)

First Plugin Source

Create the __init__.py file

$ cd ~/work/my_plugin/pelican/plugins/my_plugin
$ vi __init__.py

and fill it with:

# coding: utf-8
""" Tableize adapt to a Pelican's plugin """
__title__ = 'my_plugin'
__version__ = '0.0.0'
__author__ = 'John Doe'
__email__ = "[email protected]"
__credits__ = ["John Doe, Jane Doe, Don Doe"]
__maintainer__ = "Jill Doe"
__status__ = "Stable"
__license__ = 'GPLv2'
__copyright__ = 'Copyright 2024'

from .tableize import register  # NOQA
Clone this wiki locally