Space Panda

Behind The Curtain

As a start why not actually have a look at this website? As you've seen it just consists of a bunch of HTML files. Of course I did not write each and every one by hand. Instead I'm using a Static Site Generator.

That means, I write the content reStructuredText and a program generates the HTML files.

So it's almost like WordPress. The only difference is that I don't have any active code on the webserver, which means that the server has a smaller attack surface.

There are way too many static site generators in the world to choose from, so I made my selection by what markup languages are supported and what language the generator itself was written it. So it boiled down to Pelican 1.

Getting Started

The quickstart, as provided by the good people over at Pelican, is a reasonably good start. Once you ran pelican-quickstart (don't worry about all those questions too much, you can change the values later again) you will get a directory structure like this:

.
├── content
├── output
├── pelicanconf.py
└── publishconf.py

content is where you put, well, the content. And the script will generate all the HTML files in output.

There are two script files, as you can see: pelicanconf.py and publishconf.py. The former is used during development, i.e. while you're in the process of writing you websites, and the latter is used when you generate the website for publishing.

Usually your publishconf.py should contain this line somewhere at the top:

from pelicanconf import *

Which means that all configurations in pelicanconf.py also apply in publishconf.py but additional settings in the latter file are also used during the generation.

How to work with it

What I usually do is, I run a webserver in the output directory:

$ cd output
$ python -m http.server --bind 127.0.0.1 8000

And open http://127.0.0.1:8000 in my browser. Now the work on the website proceeds in this way:

  1. Edit the content files,

  2. Run the generator (pelican -s pelicanconf.py),

  3. Refresh the website,

  4. Repeat until happiness sets in.

The content

By default pelican expects you to create content in specific directories, which means you have to create the folders first:

├── content
│  ├── articles
│  ├── images
│  └── pages
├── output
├── pelicanconf.py
└── publishconf.py

I guess it's obvious what goes into the images folder. But what's the difference between articles and pages?

In pelican articles are the main content of your page: blog posts, galleries, limericks, or whatever floats your boat.

pages are everything else like mission statements, contact page, About the author and such.

Both pages and articles can be written in Markdown, reStructuredText, or HTML. I prefer reStructuredText, so an article could look like this:

#############
Article Title
#############

:date: 2019-01-21 14:23
:author: Darel B. Tudar
:tags: example

Here comes the text!

Only date and title are required. The author is taken from the configuration file and everything else is left emtpy if you don't specify it.

You can find the description of the meta data for articles and pages at Pelican's documentation website 2.

Theming

To select the theme you could clone one of the available themes and put the reference to it into your pelicanconf.py:

$ git clone https://github.com/BYK/pelican-neat.git

And then inside your pelicanconf.py

THEME = './pelican-neat'

It's fairly easy to write your own theme by looking at the basic theme and reading up on it in the documentation.

Plugins

There are many plugins over at https://github.com/getpelican/pelican-plugins to enhance the generation of your site, like galleries, thumbnails, comments, or analytics (by using 3rd parties like disqus or google analytics, if that's something you'd like to do to your visitors).

Versioning

I use git for versioning both the theme and the website. However, I keep the theme in a separate repository, because it seems like bad style to mix the content and the theme in the same repository.

.
├── website
│  ├── .git
│  ├── .gitignore
│  ├── content
│  ├── output
│  ├── pelicanconf.py
│  └── publishconf.py
└── theme
   ├── .git
   ├── static
   └── templates

My .gitignore looks pretty much like this:

output/
**/__pycache__/**

But I don't put big pictures on my website, so my repository doesn't blow up.

Some final words

Pelican can do much more than what you see here (from translations to RSS/Atom feeds). One of the nice, but for beginners overwhelming, parts is that you can configure almost everything. Don't want to call the folder for your articles articles? You can configure that. Want to have your images in a directory outside the normal file structure? You can configure that.

Once you get comfy with how it works and have set up your first playground website, revisit the documentation to find all the nice features and gems that Pelican offers.

Footnotes

1

A heads-up: From here in in I'm mostly just regurgitating the well written documentation of Pelican, so you might as well skip this website and go straight to their docs. You have been warned.

2

As it is ReadTheDocs, you can also download the HTML files as a zip for offline viewing.


Tagged as website