The flying start of your blog with Pelican and Github Pages

Are you new in the beautiful world of web development? Or maybe you're a seasoned webdev' but you don't want to take too much time on your personal blog?

I've got your back! Well, more exactly, Pelican has your back. ;)

What is Pelican?

Pelican (anagram of the word calepin which means notebook in French) is what is called a Static Site Generator (SSG).

An SSG is a software tool that generates a full static website composed only of HTML and CSS files (sometimes, some client-side javascript). This software uses raw data like files in Markdown and some templates to render your website.

It's a very efficient way of creating a website, especially a blog! Just install this tool and now, you just have to write your articles. ;)

That's what we are going to do in this post.

Installation

Pelican is writted in Python, so some knowledge in this programming language is a bonus.

Installing Pelican is very easy, a pip command and it's done!

But first, take the habit to create a virtual environment. It's not mandatory but with it, you don't mess with dependencies from a project to another and so on.

mkdir blog
cd blog
virtualenv -p python3 venv
source venv/bin/activate

Now, you can use this famous pip command!

pip install pelican
# If you plan to write your articles in Markdown, use:
pip install 'pelican[markdown]'

Let's start our blog

Once Pelican is installed, we can make the skeleton of our blog and a bit of configuration with the pelican-quickstart command that Pelican provided us.

Here is the output and the choice I made for my blog.

Welcome to pelican-quickstart v4.8.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.


> Where do you want to create your new web site? [.] 
> What will be the title of this web site? ttbb's blog
> Who will be the author of this web site? ttbb
> What will be the default language of this web site? [fr] en
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) 
> What is your URL prefix? (see above example; no trailing slash) https://tt-bb.github.io
> Do you want to enable article pagination? (Y/n) 
> How many articles per page do you want? [10] 
> What is your time zone? [Europe/Rome] Europe/Brussels
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) 
> Do you want to upload your website using FTP? (y/N) 
> Do you want to upload your website using SSH? (y/N) 
> Do you want to upload your website using Dropbox? (y/N) 
> Do you want to upload your website using S3? (y/N) 
> Do you want to upload your website using Rackspace Cloud Files? (y/N) 
> Do you want to upload your website using GitHub Pages? (y/N) 
Done. Your new project is available.

Some explications :

• Source directory : remember, we are on our blog/ directory, so I use . as the source of our blog.
• URL prefix : as you can see, I will host my blog on github.com using Github Pages. I will talk later about it.

After answering all these questions, we now have the first stage of our blog : the skeleton and some configuration file.

Here is what it looks :

blog/
├── venv/                # Virtual environment
├── content/
 │   └── (images)/        # to stock our images, ah!
 │   └── (pages)/         # optionally add yourself if you plan to create non-chronological content
├── output/
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

Some digression about github pages

As said earlier, I'm gonna host my blog with Github Pages. Github imposes us the output directory of our website : /(root) or /docs/. I could choose root and only commit my output directory on my repository. But I want to have all my configuration files hosted too. So, we have to tell Pelican that our output directory is docs/.

For that, add in your file pelicanconf.py this line :

 OUTPUT_PATH = 'docs/'

And change in your Makefile file the seventh line to that :

OUTPUTDIR=$(BASEDIR)/docs

Now, we can delete the output/ directory.

Time to write some content

I will be using Markdown to write my posts but know that reStructuredText format is also accepted.

All of our blog posts will be stored in the content/ directory. If you have some page, like About me or Contact me, it's better to put them in the content/pages/ directory.

Here is my first article, it's very brief but he!, that's gonna make it.

Title: Hello, World
Date: 2022-09-07 12:42
Tags: hello
Category: hello
Authors: ttbb
Summary: Some Hello within my head

# Hello, world!

Welcome on my blog, folks

The first six lines are what we call metadatas. It is used to share information from your article to the templates. Some themes (we will talk about them later) authorized supplementary metadatas.

Next, we have a super original title and a paragraph.

Here is a list of all basic metadatas included with bare Pelican.

And here is the publishing

The canonical way

We can use the pelican canonical way to deploy our website. We do that with the pelican command :

pelican content/

(Remember, we are still in the blog directory. ;) )

Automation, automation

If you answered “yes” to the question Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n), a tasks.py and Makefile are generated in the root of our project. We can use and personnalize some command. So, I'm gonna use the commands define in the Makefile file.

make devserver
# It runs both:
#    - make regenerate   # to re-generate our markdown to html
#                        # after every modification
#    - make serve        # to preview it in our browser

Here is the output of this command if everything was right setup :

  --- AutoReload Mode: Monitoring `content`, `theme` and `settings` for changes. ---

-> Modified: settings, content, theme. re-generating...
Serving site at: http://127.0.0.1:8000 - Tap CTRL-C to stop
Done: Processed 1 article, 0 drafts, 0 hidden articles, 0 pages, 0 hidden pages and 0 draft pages in 0.27 seconds.

As mentionned, we can find our blog in http://127.0.0.1:8000.

Themes

Wow, the design is not very modern... Don't worry, we will change that!

We can find a very good list of very good themes in here. Choose your one and only one, your bestfriend, your soulmate. Hum...

I choose Attila from arulrajnet.

Installation of Attila

I decide to have my theme files on my github repository. So I have to create a directory that I will call themes on my blog, it will have the path blog/themes/.

Next, I download the attila theme (via a git clone or a direct download) and I put the files on my themes folder, under the attila directory.

Resume of my skeleton

blog/
├── venv/                
├── content/
 │   └── (images)/        
 │   └── (pages)/        
 │   └── hello.md 
├── docs/
 │   └── ...
├── themes/
 │   └── attila/
 │       └── ...
├── tasks.py
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

OK. My theme is downloaded. What's next? We have to tell Pelican that we have a new theme. We do that with the built-in command pelican-themes.

pelican-themes -U themes/attila/
# Verify that our theme is installed :
pelican-themes -l

Next, signal to your blog which themes to use. For that, modify your pelicanconf.py and add this line :

THEME = 'attila'

Publishing our blog on Github Pages

First thing first, you have to create a new repository. Important rule: it has to be name as <your github pseudo>.github.io. So, if my username is tt-bb, my repository would be named as tt-bb.github.io.

Next, you know what to do (remember, we are on our blog/ directory):

git init
git add .
git commit -m "Initial commit: first blog post (Hello World)"
git branch -M main
git remote add origin git@github.com:<username>/<username>.github.io.git
git push -u origin main

Here, you have your code on github.com.

BUT. That's not it. You have to tel github that you want to use Github Pages. You can do that in the tab Settings, menu Pages.

After that, choose your branch you wish to deploy (here main) and select the output directory (here docs/).

Save. Wait a minute. And DONE!

Notice that you can track the progress of the publishing progress in the tab Action :

Conclusion

That's it folks. Write more content, commit, publish and show me your work. ;