- 1. Installation, hosting and use of Pelican
- 2. What is Pelican
- 3. Installation
- 4. Let's start our blog
- 5. Time to write some content
- 6. And here is the publishing
- 7. Themes
- 8. Publishing our blog on Github Pages
- 9. Conclusion
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. ;)
Pelican (anagram of the word calepin which means notebook in French) is what is called a Static Site Generator (SSG).
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.
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 install pelican # If you plan to write your articles in Markdown, use: pip install 'pelican[markdown]'
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?  > 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
As said earlier, I'm gonna host my blog with Github Pages. Github imposes us the output directory of our website :
/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
For that, add in your file
pelicanconf.py this line :
OUTPUT_PATH = 'docs/'
And change in your
Makefile file the seventh line to that :
Now, we can delete the
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
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.
We can use the pelican canonical way to deploy our website. We do that with the
pelican command :
(Remember, we are still in the
blog directory. ;) )
If you answered “yes” to the question Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n), a
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
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.
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 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
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.
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 -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'
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
git init git add . git commit -m "Initial commit: first blog post (Hello World)" git branch -M main git remote add origin email@example.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
Save. Wait a minute. And DONE!
Notice that you can track the progress of the publishing progress in the tab Action :
That's it folks. Write more content, commit, publish and show me your work.