Skip to content

Plugin Development

Jump to bottom
Egbert edited this page Jun 30, 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.

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

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

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.

Clone this wiki locally