Jeff's Pelican SSG Theme

By jeffmackinnon


I have been using the theme that I started working on in March 2021, and even branched a copy for JMK Engineering.

Since then I have added a bunch of features, customizations, etc to it so that I can customize most of it from the pelican configuration files.

I have also moved the repository from Github to a self-hosted Gitea instance. It's not something that I'm expecting people to be collaborating a lot on, so self-hosted works best for me. Below I outline some of the features, but I doubt I will update this often, so check the README for the latest information.


There are a lot of different customizations. This includes both variables in the file and custom HTML that you can add. It is this custom HTML that I need to figure out so that I can add it with JINGA but that it is outside of the installed theme. I'm thinking that it may be a set of variables where you add the full path to these files, but that is for V2.

Pelican Configurations

The pelican configurations are broken into a bunch of areas to make things a bit cleaner:

  • Site Wide
  • Sidebar
  • FrontPage
  • Commenting

Site Wide

The site wide configurations include:

THEME_COLOUR = 0 # Pick the colour.
# 0 => default
# 1 => Blue

SITELICENSE = '<a rel="license" href=""><img alt="Creative Commons License" style="border-width:0" src="" /></a><br />This work is licensed under a <a rel="license" href="">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.'

# The Social Things
SOCIAL_TWITTER = 'jeffmackinnon'
SOCIAL_GITHUB = 'Jeffmackinnon'
SOCIAL_LINKEDIN = 'jeffmackinnon'
SOCIAL_FLICKR = 'jeffmackinnon'
MICROBLOG = 'microblog'

The THEME_COLOUR has two options, but I will be adding options as I build new sites for little projects that I have in mind, the colour you see on this site is the default and blue for JMK Engineering inc..

The SITELICENSE is straightforward, along with the tracking code.

The SOCIAL_SHARE will add share links for the socials you fill out below. Those links will also show up in the header.

I have plans for the MICROBLOG variable, but still haven't gotten around to building it. My thought is to remove this category from the general homepage posts and have it as a separate page on the site. Its on my list of things to do, but for now I'm liking Mastodon so I'm doing most of my microblogging there.

The Sidebar

The things in the side bar include:

## Sidebar things
#DUCKDUCKGOSEARCHURL = '' # This is the only search that I have working right now.
BIO_IMAGE = 'jeffmackinnon.jpg' # Make sure that this is in the "images" folder
CONTACT_PHONE_NUM = '+1 (902) 555-1234'

# This is for and is located in the sidebar
FEDIRINGURL = ''   # This is needed because the SITEURL includes the https:// and Fediring doesn't want that part.

Currently I'm depending on Duckduckgo for the site search. There are other options out there but getting them to play nice on my windows machine hasn't worked out, and for now this works fine.

The BIO_IMAGE is an image that you put in the images folder and is shown at the top of the sidebar.

The SHOWCATEGORIES and SHOWTAGS determine what you show in the sidebar.

And then the CONTACT_xxxx are self explanatory.

If you are active in the fediverse and want to be part of the fediring then this is the place to to do it. I'm hoping to get rid of the need of the URL and tie it to the SITEURL but it can't have the http(s)://.


For my homepage here this wasn't necessary, but I did want to have some control of what I add for my business site, so this is what I did:

# Frontpage customization
TAGLINEHEAD = 'The cool headline'
TAGLINESUBHEAD = 'The sub-header'
TAGLINE = 'Now this is going to be super cool, think of all the things we can teach you about. It is going to be amazing'
BANNERLINK = 'services/'
BANNERIMAGE = 'images/20130923124523.jpg'
CORNERSTONE_CONTENT = True # If true add the html you want in include/cornerstone.html
NEWSLETTER = '' # place your newsletter embed information here

This is all self-explanatory, however, there is a catch. There is a .html file that you need to edit to make the CORNERSTONE_CONTENT work. Its in the templates/include/ folder and is called cornerstone.html.

You can basically put anything you want there and it will work.

INCLUDECATEGORY = True # This includes the Category in the article list
MOREBUTTON = True #This adds the "MORE" to the article list

The INCLUDECATEGORY and MOREBUTTON affect how posts will look on the homepage, category page, tag page, etc. With pelican you can only have one category, so this is a good place to let your user know what they are getting into. The MORE button explictly lets people know that there is more to this post.

Personally, I have both these set to False to clean up the homepage here, but have both set to True on the business site.


Commenting can be a pain with static sites, but I have come up with three ways to do it. Twitter (will probably remove that in the future), Mastodon (not working right now, but on my list to fix), and Hashover.

With these variables you can get any of them working.

# Commenting
MASTODON_EMBED = '' # This is where you add the Mastodon Embed code, it needs a overhaul so I will link to the repo when I have time to play with it.
# I'm using HashOver for comments, but there are a few different ones that you can use.
COMMENT_EMBED ='' # This is the emdbed code that you need for the comments.

The way that I have the COMMENTS set up can allow you to use any third-party commenting system like Commento or you can self-host with Hashover like me.


Finally there is the article_footer.html Currently this is the only article based customization that I have added, but that's because of how powerful RST is for creating posts. That said I do have some cleanup to do to make this work cleaner, but that is a minor feature for later.

Feature Requests and Help

If you like this theme and want to use it clone the repo and get started.

If there are any questions or feature requests, please let me know below in the comments, or tag me on Mastodon, I'm not checking my Twitter very often so that won't be a good place.

This post is part 7 of the "How I Pelican" series:

  1. Installing Pelican for the first time again
  2. I updated a theme
  3. EXIF data with a pelican-photos Gallery
  4. V1 of the theme published
  5. Custom CSS per page or article with pelican
  6. Batch Files are your friend
  7. Jeff's Pelican SSG Theme