There are two .. three hard parts to overcome building a website ..

1. Find the right technology.
2. Writing the content.
3. Creating a look and feel for your content.

After a whole lotta dithering I built this personal blog/website with Pelican. That information is here Building a Pelican Website. Dropping a theme onto a website can be the hardest part of the process.

In the end, I eventually found a 'it'll do' theme and have done some minor tweaks to it. For my future reference, here is my howto.

At some point Pelican made some changes to the way they are dealing with themes and have made it substantially easier. I've purged the original notes.

My basic process is ..

• Find some themes you like
• Install the themes
• Test the themes
• Tweak the theme
• Rebuild it as your own

Find some themes you like

How does one get the feel and 'branding' right? That is certainly one of the things that made it hard for me.

There is a git repo on Github getpelican/pelican-themes: Themes for Pelican where a number of themes have been pushed by members of the Pelican community. Some are simple, some are complicated, some are very targeted, and some haven't been updated in years. Ultimately they are there as examples of different ways themes could be done. Personally I would like to see something like CSS Zen Garden for the Pelican themes¹, where there is some standard content that is used to showcase the themes.

As you scroll through the themes it is worth noting when the theme was last updated, you may find that versions of Pelican and Python have moved on and that lovely theme ends up throwing a few errors when you build the site. You may need to decide if it is worth trying to fix or just move on.

As I was going through some of the themes to test, I did end up changing my focus on what I was after. Although I like those cute calendar things for the date of a post, I'm probably not going to be doing many things that are strictly date relevant. It is probably well worth sitting down with a pen and paper and drawing some mock ups of what you think is important and be prepared to change as new ideas from different themes come into play.

Basically I was looking for layout and structure of the theme as that is probably going to be harder for me to tweak. Although having the right colours, fonts and images is nice, they are relatively easily changed.

Probably most important to note that at some stage you should actually make a decision and go with something rather than spend eternity looking for the right theme you don't have to do anything to. Use the "it's not right" as an opportunity to learn and develop new skills.

Install the themes

To install the themes, start by cloning them all from Github ..

cd ~/Projects/Websites/
git clone git@github.com:getpelican/pelican-themes.git

Doing it this way, the themes will be in subdirectories of ~/Projects/Websites/pelican-themes. Most of the themes have their own repository, and if you really know the one(s) you want, you can just grab them. But if you are playing, may as well grab the lot to experiment with.

You can also download a zip file of the themes, but if you want to check updates and fixes down the track you'd need to go through that process again.

I'm using the Flex theme, so I am going to install that. Start off by switching into your Pelican virtualenv ..

cd ~/Projects/virtualenvs/pelican
source ./bin/activate

.. move into the directory with all the themes, and use pelican-themes to install the theme ..

cd ~/Projects/Websites/pelican-themes
pelican-themes -i Flex

The themes will end up being installed in the virtualenv for Pelican eg ~/Projects/virtualenvs/pelican/lib/python3.10/site-packages/pelican/themes/Flex

Updating themes

Themes change, get updated for fixes or to work with newer versions of Pelican or Python. If you are in the process of testing and trying out different themes, you are likely to want to regularly update the themes.

Get into your Pelican virtualenv, change to your themes directory, pull the repo to get the latest versions, upgrade your theme ..

cd ~/Projects/Websites/pelican-themes
git pull
pelican-themes -U Flex

Remember to test and check that there are no breaking changes to your theme before you push the updated set of files to your production site!

Test the themes

To configure a theme you need to tweak the pelicanconf.py file to refer to the theme.

pelicanconf.py

# THEME = "notmyidea"
# THEME = "simple"
THEME = "Flex"

If you are running the simple web server with make devserver, you will probably need to stop and restart to rebuild the theme properly.

I've kept and commented out the default themes as handy test cases. If you do not specify a theme it should end up with the default 'notmyidea' theme. It really can be worthwhile just checking what the 'simple' theme does to your content (it's plain ol' html). As I went through I had a list of 6 themes I found interesting and with some dummy content, checked they were sane and worked with some of the things I wanted.

To remove the unwanted themes once you have settled ..

pelican-themes -r notebook

Tweak it

If the theme isn't perfect, you can make some changes to bring it more in line with what you are after. Depending how enthusiastic you get, you may get to a point where you really should fork the theme and really make it your own. I am expecting to have to revisit these changes when the next version of theme I am using is released as there are comments about breaking changes coming.

I made a couple of minor tweaks to use the Atkinson Hyperlegible font.

Change the CSS

The Flex theme has a configuration for CUSTOM_CSS² that allows you to define a custom css file with your own tweaks in it. These changes override the css from the theme.

pelicanconf.py:

CUSTOM_CSS = "extras/figjam.css"

content/extras/figjam.css:

@font-face {
    font-family: 'Atkinson Hyperlegible';
    src: url('fonts/Atkinson-Hyperlegible-Regular-102a.woff2') format('woff2'),
         url('fonts/Atkinson-Hyperlegible-Regular-102.woff') format('woff'),
         url('fonts/Atkinson-Hyperlegible-Regular-102.ttf') format('ttf');
    font-display: swap;
  }

body {
    font-family: Atkinson Hyperlegible,Roboto,Open Sans,Liberation Sans,DejaVu Sans,Verdana,Helvetica,Arial,sans-serif;
  }

Of course I had to copy the font files into content/extras/fonts/ so the css would correctly refer to them.

Change the Templates

After changing the font, I wanted to change the footer to add that I was using the Atkinson Hyperlegible font as well as Pelican and the Flex theme.

First thing I did do was track down the actual file used to build the footer in the Flex templates. I found it in the themes directory at <theme_path>/templates/partial/flex.html and changed it in place. But thought that there really should be a better way to do that.

Funnily enough, there is .. THEME_TEMPLATES_OVERRIDES³. That allows one to specify an alternate path root to template files that will replace the theme's template files when the site is rebuilt.

I'm going to use a directory tweaks for my tweaked templates.

pelicanconf.py:

THEME_TEMPLATES_OVERRIDES = ['tweaks']

I created the directory and copied the flex.html file from the theme in there and made the changes. Nope, that didn't work. I actually needed to create the same directory structure as the template needs to find partial/flex.html whether it be in the themes structure or mine. The file I needed to change was tweaks/partial/flex.html

tweaks/partial/flex.html:

<p>
{{
  _('Built with %(pelican_url)s using %(flex_url)s theme and the %(font_url)s font.',
    pelican_url='<a href="http://getpelican.com" target="_blank">Pelican</a>',
    flex_url='<a href="http://bit.ly/flex-pelican" target="_blank">Flex</a>',
    font_url='<a href="https://brailleinstitute.org/freefont" target="_blank">Atkinson Hyperlegible</a>'|safe)
}}
{% if THEME_COLOR_ENABLE_USER_OVERRIDE %}
  <span class="footer-separator">|</span>
  {{
    _('Switch to the %(dark_url)s | %(light_url)s | %(browser_url)s theme',
      dark_url='<a href="javascript:void(0)" onclick="theme.switch(`dark`)">dark</a>',
      light_url='<a href="javascript:void(0)" onclick="theme.switch(`light`)">light</a>',
      browser_url='<a href="javascript:void(0)" onclick="theme.switch(`browser`)">browser</a>'|safe)
  }}
  <script id="dark-theme-script"
          src="{{ SITEURL }}/{{ THEME_STATIC_DIR }}/dark-theme/dark-theme.min.js"
          data-enable-auto-detect-theme="{{ THEME_COLOR_AUTO_DETECT_BROWSER_PREFERENCE|default('false') }}"
          data-default-theme="{{ THEME_COLOR|default('light') }}"
          type="text/javascript">
  </script>
{% endif %}
</p>

Rebuild it as your own

Heh, not sure I really have the inclination for it at this point. I think I am more likely to contribute to an existing theme I use to help them tune options to make it better.