Development Area

For troubleshooting/expanding/creating your new/existing plugin, there are four repositories involved with a SSG website:

Due to directory dependencies, the ordering of installing repositories are:

1. Pelican
2. Pelican plugins (optional)
3. Your plugins
4. Content of your website

Pelican Repository

Pelican repository is not getting any changes, if at all, assuming that you are not inserting yet another signal handler out of some 30-odd currently provided signals as this is plugin development (not Pelican rework) here.

Just clone the repository using git (no need to use gh repo clone):

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

A newly created pelican directory containing the pelican repository appears.

TIP: we have an optional 1-liner change in Pelican to greatly assist in prototyping/debugging new plugins, and that is in pelican/log.py

LOG_FORMAT='%(name): %(message)s'

Plugins Repository

If your Content-class documents does not require some extra plugins, this section can be skipped.

Separately, Pelican has a single repository for all its plugins; keep in mind that many plugins are essentially a simple link to OTHERS' people's plugin repository.

Obtain the pelican plugins by executing git (no need for gh repo clone ...):

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

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 shall remain largely in READ-ONLY mode (same as Pelican repo).

Your Plugin Repository

New plugin for Pelican benefits from having its own repository (and then git-link from the pelican-plugins page.

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 create <your-github-username>/my_plugin
cd my_plugin
# populate directories
mkdir pelican pelican/plugins pelican/plugins/my_plugin
git add .
# make your first commit called 'skeleton layout'
git commit
git push

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

Your directories should look like below in the near future:

my_plugin
├── CONTRIBUTING.md
├── .gitignore
├── pelican
│   └── plugins
│       └── tableize
│           ├── __init__.py
│           ├── tableize.py
│           └── test_tableize.py
├── pyproject.toml
├── README.md
├── requirements.txt

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). After all, we are making or troubleshooting a plugin.

Create a Markdown content file 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
#
# create skeleton directories for Pelican contents.
mkdir content content/articles content/pages output plugins/myplugin

Your directories should look like below in the near future:

.
├── CONTRIBUTING.md
├── pdm.lock
├── pelican
│   └── plugins
│       └── tableize
│           ├── __init__.py
│           ├── tableize.py
│           └── test_tableize.py
├── pyproject.toml
├── README.md
├── requirements.tx