Blog initialisation

cover

First of all I'm not a web engineer and I hate web development. There are too many framework to work with (ReactJS, Angular, jquery, ...). Javascript asynchronous system is a pain to manage at large scale. And dependencies maintainability is too much for me (yes, I'm talking about you npm). I'm not a web designer either so HTML/CSS are the enemy (mostly because I don't know how to use them at their full potentials).

This is pretty much why I quit web development in the first place and became a SysOps engineer.

Danger

This blog post is deprecated. I left it online for historical reasons. Now the blog is generated with MKDocs.

Theory first

This is a static website. No fancy Javascript, framework or other CMS. All pages and medias are served through a very simple web hosting setup that I will detail in another blog post later.

How is it generated then ?

I did not want to over-think too much on the website structure (HTML & company) and I wanted to focus on the content of the blog. So I searched for a tool to generate a fancy website from simple text files.

Digression

A lot of people already know about Jekyll. It's a Ruby based tool that do the job just fine. Setup some config files, write your article as plain text file, build and ... here you go a fancy website. But wait ! I didn't use Jekyll because IMHO it's overkill for my needs. Why you may ask ? Well :

  • I'm didn't know anything about Ruby so it's pretty hard to debug anything
  • Ruby package dependencies are a pain in the ass
  • Jekyll plugin are (for most the majority) community driven so a lot of them are incompatible with each other, have missing documentation or simply doesn't work
  • I have already deployed another blog a few years ago with Jekyll and I don't have goo memories. I still maintain it but it's not my cup of tee ...

So the solution then ?

I use Pelican !

logo Pelican

It's a simple static site generator tool that require only Python to run. It allow me to write my blog post as plain text Markdown. HTML files are templated using Jinja. Being a SysOps engineer, Python, Markdown, Jinja are, among other, some keyword that put a smile on my face ! (It even come with a Makefile !!)

So Pelican is a tools that generate static HTML website from Markdown files and Jinja templates.

Great ?! When do we begin ?!

Practice

I'm not going to reinvent the wheel, so follow the great Pelican Quick Start guide and then come back for more deep dive into my setup for this blog website.

Requirement

I have Python 3.9.6 installed on my PC and I'm running inside a VirtualEnv.

Create the VirtualEnv : 

python3 -m venv venv

Get inside : 

source venv/bin/activate

Install the required packages : 

pip install "pelican[markdown]"

File organization

This is my current folders/files layout (FYI this is the default one provided by Pelican settings): 

.
├── Makefile
├── content
│   ├── articles
│   │   ├── init-en.md
│   │   └── init-fr.md
│   ├── images
│   │   └── logo.png
│   └── pages
├── output
├── pelicanconf.py
├── publishconf.py
├── tasks.py
└── theme
    └── flex

  • The content folder contains all the articles, pages and medias sorted in three folders :

    • articles for blog posts
    • images for media contents
    • pages for additional static pages on the blog

  • The output folder will contains all the generated HTML and CSS static files after building the website.

  • The theme folder contains the current website theme. I'm currently using the Flex theme from the community.

  • The files Makefile and tasks.py is auto generated by Pelican when creating the project with Pelican quick start guide

  • The file pelicanconf.py contains default Pelican settings.

  • And then publishconf.py contains Pelican specific configuration to apply when publishing the blog.

Configuring the blog

I use the default configuration provided during the Pelican quick start guide and just added two are three additional configuration.

Building the blog

Now that I have a full website, I need to build it.

When I'm developing the blog (or when writing articles), I'm using the following commande : 

make devserver
It build all the blog pages and serve it with à small local webserver accessible at http://localhost:8000.

When I'm happy with the look of the blog/articles, I use the provided commande to build a publishable version of the website : 

make publish
All the website files are now generated in the output folder : 
output
├── 404.html
├── archives.html
├── authors.html
├── categories.html
├── drafts
│   ├── init-fr.html
│   └── init.html
├── images
│   ├── getpelican.jpg
│   ├── getpelican.png
│   └── logo.png
├── index.html
├── tags.html
└── theme
    └── ...

The main difference between those commandes is that publish use the publishconf.py config and devserver use only pelicanconf.py

Conclusion

Now I have a fully built blog environment and I only need to write new articles, make publish and voila.

I a futur blog post, I will explain how I'm hosting those static file to make them accessible on internet.