Pelican with github pages

Pelican is a static site generator written in python which allows you to write your content directly using reStructuredText or Markdown. In this blog post, we will discuss how to create and host a static site using pelican and github pages.

Installation

Lets wrap all our installations inside a separate virtual environment using python virtual environment wrapper.

Install python virtualenvwrapper

After installing virtual environment wrapper, create a new environment for our project:

$ mkvirtualenv pelican-blog
$ workon pelican-blog

Run pelican installation:

$ pip install pelican

Checkout more installation options for pelican

Run markdown installation for writing the site contents:

$ pip install Markdown

You can also use reStructuredText for writing your content instead of markdown.

Quickstart your blog

Now we have finished all our installations and let’s create a skeleton for our site using the pelican-quickstart command. This will ask you few questions and will pre-populate the settings data as per your answers. These settings can be changed at any point of time.

$ pelican-quickstart

Please see how I have answered the quickstart questions below:

Welcome to pelican-quickstart v3.4.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? Sreekanth's Blog
> Who will be the author of this web site? Sreekanth
> What will be the default language of this web site? [en]
> Do you want to specify a URL prefix? e.g., http://example.com (Y/n)
> What is your URL prefix? (see above example; no trailing slash) http://sreekanthkaralmanna.github.io
> Do you want to enable article pagination? (Y/n) How many articles per page do you want? [10]
> Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n)
> Do you want an auto-reload & simpleHTTP script to assist with theme and site development? (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 at /home/sreekanth/Documents

Once you finish with all those questions, you will be having a directory structure as follows:

yourproject/
 ├── content
 │ └── (pages)
 ├── output
 ├── develop_server.sh
 ├── fabfile.py
 ├── Makefile
 ├── pelicanconf.py # Main settings file
 └── publishconf.py # Settings to use when ready to publish

Customise your theme

Pelican comes with a default theme for every site generated. But you can use a variety of other themes to beautify your site.

In order to include your desired theme, clone your preferred theme and save the theme to a theme directory inside your project folder. Now tell pelican that it has to use this particular theme to generate html for your site. In pelicanconfig.py, add the following:

THEME = "themes/theme_name"

Also make sure to change your pelican settings as per the settings given in the theme documentations(if any)

Writing your blog content

We are done with configuring our pelican site, now let’s start writing our blog contents  inside the content folder. Below given is a sample markdown file.

Title: Pelican Test Blog
Date: 2014-05-01 10:00
Category: Python
Tags: python
Author: Sreekanth
Summary: Pelican blog for testing.

A Pelican blog for testing

Generate html files and run your site

We are all done to test our site locally.

The following command will create the output folder for your site and serves your site locally at http://localhost:8000.

$ make devserver

Run the following command to stop the localhost server:

$ ./devserver stop

Publish your blog using Github pages

For hosting your blog using github pages, create a repository named username.github.io and this will be the remote repository for your site. Contents of your output directory has to be stored in this repository.

After creating the github repository, push your output files to the remote repository. Follow the steps given below for doing the same.

$ cd output
$ git init
$ git remote add origin https://github.com/username/username.github.io.git
$ git add --all
$ git commit -m "initial commit"
$ git push origin master

We are all done with hosting our pelican site using github pages. Checkout username.github.com to see your site on live.

Also checkout this slideshow explaining hosting pelican sites using github pages

Happy Blogging 🙂

  • Aaron

    A very simple introduction. This is the clearest example yet. Thank you very much! Many other tutorials use ghp-import but it’s not currently working on windows. Your git example at the end shows how to easily do it ‘manually’. Thank you again

  • Ali Abdulrahman

    thank you for this helpful post