Write a website with Python and Pelican (reStructuredText and Markdown) via GitHub Pages

Tue 25 November 2014

Recently, I had an adventure with Python and Pelican, a static site generator tool. Writing the scripts to use it efficiently with GitHub Pages was fun, and now it's super easy to update and maintain my website. I wanted to share my experience through a guide on how you could do the same.

Necessary stuff:

GitHub web server hosting GitHub (another service can be used of course, but for this guide and my personal website I've used GitHub as it's simple and free.)
A text editor of choice (vi, nano, Emacs, Sublime Text, TextMate...)
Python 2.7.x or 3.3+
Pelican (pip install pelican)

Markdown (pip install markdown) if you intend to use it

How does it work?

The following steps must be done in order to host your website successfully on GitHub Pages:
Create a GitHub account if you haven't got one already.
Create a GitHub Pages entry. Use the organization site option.
From here, it's all about structuring your program properly in order to be able to use it the way I use it.
  1. Create a new repository 'username.github.io-src' on GitHub and clone it into your projects folder. I removed the '-src' suffix from my local version

    git clone https://github.com/username/username.github.io-src username.github.io

  2. Change to that projects local directory

    cd username.github.io

  3. Clone your organisation GitHub Pages repository into it under folder 'output' (Pelican's default output directory)

    git clone https://github.com/username/username.github.io output

  4. Place this script to your root 'username.github.io' project folder (not the output folder!)
    What this script does is deletes everything except the '.git' repository information in the 'output' folder, since you will be regenerating the website every time you run the 'pelican <args>' command (contained within this script also). It also uses the command line arguments as the 'git commit -m <message>' message to push to both your source and output folders. It will not run if Pelican does not exist on the system and it will not push to remote repositories if Pelican fails.
  5. Issue tree -L 2 to see the current structure

  6. Issue ./publish <commit message> to publish your site

  7. Access your new site @ http://username.github.io

Category: Python Tagged: Python Pelican blog website reStructuredText Markdown GitHub


Page 1 of 1