I have aversion to most areas of web development, so I usually steer clear from it.

The problem arrives when I have to create my own website. I like simple websites, but not to the extreme of plain text HTML. I played around with several static site generators, but they all seem too complex for my use case. What I want is an extremely simple tool that has simple templating engine and just translates markdown files to html files.

I ended up programming my little, extremely simple python script to do exactly that and nothing else, elucidator¹. Infact, this page is generated by it. Of course I could have used something that already exists, but I like programming stuff and it was a good practice.

Generating

The procedure for the site generation is simple:

1. Load the config file
2. Copy over the static content(images, CSS etc.)
3. Go through every markdown file in content folder and generate HTML from it.
4. Done!

I do not want the script to do any link resolution or anything that requires either going through the markdown files multiple times or editing the resulting HTML files.

Loading the config file is simple. The main config file is presumed to be in the root directory of the website. It specifies the location of theme and output directories, and also the static content directories. The markdown files are presumed to be in content\. Apart from the required variables, it can also include any amount of “global” variables, that are used during generation of every page. Those are useful for stuff like webpage name or footer.

After loading the config file, we copy over all the non-HTML files in theme directory to output directory. We also copy over all the specified static directories in content directory.

The script then goes through all markdown files in the content directory and parses them. The markdown file has a YAML header with variables that apply only for the specific file. To generate HTML from the markdown, I use Python-Markdown with suitable setup of extensions. The output HTML is not further edited.

For templating, I use moustache, specifically the chevron implementation. It is extremely simple templating engine, with no complex logic and simple syntax. The template files itself are just HTML files with the templated parts included. The script uses base.html for all the pages but the root index page, for which it uses index.html template. The templating process is simple, it basically does a simple string replacement in the template file. We use both the global config and file-specific config to fill the template.

And that is basically it. As I said it is simple, it fits into 135 lines of Python after all.

Hosting

The website is currently hosted using a Caddy 2 on a VPS from Hetzner. This is in contrast to my previous setup, which was nginx on a Raspberry Pi 3. I switched to Caddy mostly from curiosity and because of it’s automatic HTTPS setup. The Raspberry Pi’s SD card died multiple times and it proved to be somewhat annoying to keep alive with my ISP starting to change my IP adress multiple times a week.