Why using Pelican/github pages?

Pelican is a static site generator, written in Python. I chose to create my blog using pelican because of several interesting features:

  • Generate a static html code, allowing to upload your sources on virtually every web server (including github pages).
  • Many themes to customize your own site and a wide collection of plugins to add new functionalities.
  • New posts can be easily added by creating Markdown flavored text files.
  • If you use github, Pelican sources and html output are version controlled.

Basically, you won’t have to write a single line of html.

Before starting, install dependencies

Install Pelican, Markdown and ghp-import with pip or your favorite package manager

sudo pip install pelican Markdown ghp-import

Verify that the pelican version is 3.5.0+, else if you want to be sure to have the last version download it directly from pelican github repo

Create a github repo to host your site

  • First of all, verify that you have a github user account and not a project account, see [user vs project account] (https://help.github.com/articles/user-organization-and-project-pages/) at github. You will find a load of tutorial elsewhere for project accounts.

  • Create a github repository with readme, python gitignore and license to init the master branch and name it your_github_account_username.github.io. For example mine is a-slide.github.io. This is a very specific repo from where github pages will render your website from the html files in it.

Example for my blog:


  • Clone you repo locally

git clone https://github.com/a-slide/a-slide.github.io.git ./my_folder

cd ./my_folder

  • When using github user pages, everything on the master will be published so we have to create a new branch to host your pelican sources

git checkout -b source

Init your blog with pelican-quickstart

  • From the repo folder, you can create your pelican website sources with a useful command line interface provided by pelican-quickstart.


See bellow an example with my configuration options :

> Where do you want to create your new web site? [.] ./
> What will be the title of this web site? Drowned In Genomics
> Who will be the author of this web site? Adrien Leger
> What will be the default language of this web site? [en] en
> Do you want to specify a URL prefix? e.g., http://example.com   (Y/n) n  ## I don't have any domain but feel free to use yours here
> Do you want to enable article pagination? (Y/n) Y
> How many articles per page do you want? [10] 5
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Y ## Really important, you'll see latter
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (Y/n) n
> Do you want to upload your website using FTP? (y/N) n
> Do you want to upload your website using SSH? (y/N) n
> Do you want to upload your website using Dropbox? (y/N) n
> Do you want to upload your website using S3? (y/N) 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) Y ## will simplify github deployment.
> Is this your personal page (username.github.io)? (y/N) Y ## Yes, because you already verified that your account is not a project account
Done. Your new project is available at /home/adrien/Programming/Pelican/Drowned_In_Genomics

Create your first post

  • In the content folder, create a file called my-first-post.md containing the following text
Title: My first post
Date: 2014-12-23 17:49
Modified: 2014-12-23 17:49
Category: misc
Tags: first, misc
Slug: My-first-post
Authors: Adrien Leger
Summary: Short version of my first blog post

This is my **first blog post with pelican**
  • Go back to the repo origin and create a local version of your website by taking advantage of the makefile created by pelican

make html && make serve

This will compile html files from your content folder in output folder and launch a server from your localhost. You can try your website at http://localhost:8000/ with your favorite web browser. You should obtain something like that:


  • Now, we are quite ready to commit all changes on github. The content of the output folder doesn’t need to be saved on your source branch. To ignore it just add output/ at the end of your .gitignore file. Then commit everything with git:

git add -A && git commit -a -m 'initial commit' && git push --all

git push - -all is needed to create branches and push all modified content in it

  • Finally you can now push the content of output to your master branch. Once again pelican provides a straightforward way to do thanks to the makefile.

make github

  • Your site is accessible online at the following adress http://your_github_account_username.github.io/
  • You can create new articles by adding more md files in your content folder
  • You can also create static pages (About, Contact…) by creating a pages folder in the content folder and adding md files in it.
  • Each time you are ready to update your site, just use make github and that’s all.

Customize your website with Bootstrap3 theme

You can find a large number of themes and plugins for pelican at pelican-theme and pelican plugins.

I tried several possible themes, but I chose to use the lovely pelican-Bootstrap3 theme created by DandyDev. It includes all the Bootstrap 3 themes from Bootswatch. I will not detail this section since it is already well explained by DandyDev. You could also have a look at the sources of my blog if you want to borrow ideas. Finally, Pelican documentation provides extensive advice to customize further your site.

Thanks for reading.

Useful sources that helped me to write this article


comments powered by Disqus