Build & Host a Website or Blog using Pelican

This is an eBook on building and hosting a website or blog using Pelican - a static site generator written in Python.

This eBook will help you achieve the following objectives:

  • You want a static website or blog (like this one!).
  • You want to host your website or blog on Github or other online hosting provider.
  • You don't want to setup a database like MySQL or a CMS like Wordpress.

This eBook is free to read online. You can purchase a PDF version from Gumroad. Future updates are free!

Cover of Pelican eBook

An outline of what we will do

  1. Install programs required for building and hosting the website - Python, Pelican, virtualenv, Git etc.,
  2. Learn how to create and work with virtual Python environments.
  3. Build a basic site structure and add pages and blog posts.
  4. Host the website online on Github. You can also upload the generated files to your web host using FTP or other means.

Requirements

The basic requirement for this course is an installation of Ubuntu Linux.

These steps have been tested on Ubuntu 14.04 LTS.

Hint

Some options if you do not have Ubuntu installed

  1. You can download the latest version for free from the website - http://www.ubuntu.com/download/desktop.

    You can easily install and use Ubuntu along with your current Operating System by following the installation guide on the Ubuntu website.

  2. Another option is to install the downloaded Ubuntu ISO in a virtual machine like Virtualbox.

  3. Yet another option is to use Ubuntu on the cloud by creating a droplet at DigitalOcean.

Install or verify Python installation

Python is installed on Ubuntu and most other Linux distributions by default. However, Python 2 is required to follow examples in this book.

You can check the version of Python installed using the following command in a terminal:

python -V

Setup a virtual environment

The second requirement is to create an isolated Python setup for our website. This is called as a virtual environment.

We can then install additional python packages in the virtual environment without affecting other programs installed on the system.

Mutiple such virtual environments can be created each independent of the other.

The virtualenv Python module can be used to setup virtual environments. virtualenvwrapper is an extension to virtualenv that makes it easier to create and manage virtual environments.

Install virtualenv and virtualenvwrapper

Install the virtualenv and virtualenvwrapper packages using the following command:

sudo apt-get install python-virtualenv virtualenvwrapper

Important

Open a new terminal session before proceeding with the next steps. Only then, the commands for creating and working with the virtual environment will be available.

Create a virtual environment

We will create a new virtualenv called site to hold all necessary programs required for the building and hosting of our site. To do this on

Open a terminal and type:

mkvirtualenv site

Output:

New python executable in site/bin/python
Installing setuptools, pip...done.

(site)vl@laptop:~$

Using the virtual environment

The setup process above should already place you in the virtualenv. Notice the change in the prompt to include the name of the virtualenv

If this is not the case, you can always switch to the virtualenv using the following command:

workon site

Within the virtualenv, you can install additional Python modules or run scripts installed by these modules.

To exit, type:

deactivate

You will be returned back to the prompt.

Note

You will always need to be in the virtualenv when you are working with the site.


Install Pelican, the static site generator

Pelican is a static site generator written in Python.

We can write content in a text editor using reStructuredText or Markdown formats.

The use of templates make it easy to change the entire look of the site. Pelican has support for Jinja2 templates.

It includes programs for generating and deployment of the site.

Switch to the site virtualenv we created before:

workon site

Install Pelican using pip, the Python package management system:

pip install pelican

Pelican should now be installed with all dependencies.

Add support for Markdown

Out of the box, Pelican supports writing content using the reStructuredText syntax. To add support for writing content using Markdown, we will need to install the corresponding Python module.

Install markdown using pip:

pip install markdown

Git

We will use Git for the deployment of our website i.e., pushing content to a remote server (Github, in this eBook) to make the website available online.

Installation

Install Git using apt

sudo apt-get install git

ghp-import for Github deployment support

The ghp-import script simplifies the process of publishing our website on Github. It can be installed using pip:

pip install ghp-import

With all the dependencies installed, we can now proceed towards creating the website.


Create the site

Let's create a basic site using Pelican.

First, create a new directory:

cd
mkdir samplesite
cd samplesite

Activate the site virtualenv we had created earlier. This needs to be done every time we need to work with the site:

workon site

Setup a basic structure for the site using the pelican-quickstart command:

pelican-quickstart

We will be asked a series of questions for the inital site configuration.

Hint

You can press ENTER to accept the default value for any option.

Basic configuration

The first series of questions are related to the basic configuration of the site

We will be creating our website in the samplesite directory. Since we are already in this directory (cd samplesite), we will just use the default value . The . (dot) here refers to the current directory.

Next, we enter a title for our website. I have used Sample site.

The author name will be displayed in blog posts.

For language of the website, I have used the default value (en - English)

Welcome to pelican-quickstart v3.3.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? Sample site
> Who will be the author of this web site? Vimalkumar Velayudhan
> What will be the default language of this web site? [en]

URL prefix, pagination and scripts

If you already have a domain registered for the webiste, enter it here (URL prefix) otherwise, type n.

Article pagination enables navigation of blog posts. This is the number of blog posts displayed per page. I've used the default(10).

A Makefile enables us to use commands for site generation and hosting.

You should also enable the creation of the auto-reload script. This script generates the website whenever there is a change in content.

> Do you want to specify a URL prefix? e.g.,
  http://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10]

> Do you want to generate a Fabfile/Makefile to automate
  generation and publishing? (Y/n) y

> Do you want an auto-reload & simpleHTTP script to assist
  with theme and site development? (Y/n) y

Hosting options

The next series of questions relate to how we are going to host our website online.

We will need to choose from one of the many options available - FTP, SSH, Dropbox, Amazon S3, Rackspace or Github.

I will be using Github as an example in this course. The Github user name of the account is samplesite and when published, the site will be available online at http://samplesite.github.io

> 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) n

> Do you want to upload your website using GitHub Pages? (y/N) y
> Is this your personal page (username.github.io)? (y/N) y

Done. Your new project is available at   /home/vl/samplesite

At the end of the process, pelican-quickstart saves all settings to a file called pelicanconf.py.

Here is a listing of files produced on running pelican-quickstart

(site)vl@laptop:~/sample-site$ ls -l

drwxrwxr-x 2 vl vl 4096 Aug 30 10:26 content
-rwxr-xr-x 1 vl vl 2197 Aug 30 10:26 develop_server.sh
-rw-rw-r-- 1 vl vl 1809 Aug 30 10:26 fabfile.py
-rw-rw-r-- 1 vl vl 3856 Aug 30 10:26 Makefile
drwxrwxr-x 2 vl vl 4096 Aug 30 10:26 output
-rw-rw-r-- 1 vl vl  830 Aug 30 10:26 pelicanconf.py
-rw-rw-r-- 1 vl vl  508 Aug 30 10:26 publishconf.py

With the basic site structure in place, we can now proceed towards building the site.


Build the site

Pelican includes a script that will watch for changed content and regenerate the site.

Run this script using the following command:

vl@laptop:~/samplesite$ make devserver

Output:

Starting up Pelican and pelican.server
Pelican and pelican.server processes now running in background.

(site)vl@laptop:~/samplesite$
DEBUG: Adding current directory to system path
DEBUG: Temporarily adding PLUGIN_PATH to system path
DEBUG: Restoring system path
DEBUG: Missing dependencies for asc
---
AutoReload Mode: Monitoring ``content``, ``theme`` and
``settings`` for changes.
---
DEBUG: Temporarily adding PLUGIN_PATH to system path
DEBUG: Restoring system path

 -> Modified: theme, settings. re-generating...
 WARNING: No valid files found in content.
 ... lines truncated
 -> writing /home/vl/samplesite/output/index.html
 -> writing /home/vl/samplesite/output/tags.html
 -> writing /home/vl/samplesite/output/categories.html
 -> writing /home/vl/samplesite/output/authors.html
 -> writing /home/vl/samplesite/output/archives.html
 Done: Processed 0 articles and 0 pages in 0.21 seconds.

The "Processed 0 articles and 0 pages" indicates that we haven't written any content yet! We will do so in the next section.


Preview the site

To preview the site, open http://localhost:8000 in a browser.

The home page of the site should now be displayed.

Preview generated website

To stop watching for changes, type:

vl@laptop:~/samplesite$ make stopserver

Note

You can also generate the site manually using:

make html

Afterwards, you can serve the generated content using:

make serve

To stop, press CTRL+C.

We can now start adding new content to the website.


Write content

The site does not have any content yet. Let us see how we can add a new page and a new blog post.

Important

The pelican development server should be running. Only then, Pelican will automatically generate the new page and post.

If this is not the case, you will have to generate the website manually using make html.

Create new page

We will add an About page to our website. To do this, make a folder called pages inside the content directory:

mkdir content/pages

Create a new file inside pages called about.md with the following content:

Title: About

Hello. This is a sample website created with Pelican.

Open http://localhost:8000/pages/about.html in a browser to view the new page.

The site's navigation menu will also be updated to include a link for the About page.

The About page

Create new blog post

We will now create a new blog post. Using a text editor, create a new file inside the content folder with the following content.

For example, sample-post.md

Title: Sample blog post
Date: 2014-02-01 19:45
Slug: sample-blog-post
Author: Your Name
Summary: This is a sample blog post

Welcome. This is our first blog post.

Open http://localhost:8000/sample-blog-post.html to view the new blog post.

Sample post

Hint

You can assign posts to a category using Category:

Category: Python

Adding tags to a post can be achieved using Tags:

Tags: Pelican, Howto

This must be added to the metadata before post content.

We can now proceed towards publishing this site.


Hosting on GitHub

Pelican generates a complete static version of our website in the output folder.

To host the website online, we should copy all the contents in this folder to a server. This needs to be done whenver there is a change in the website - new page, new blog post, theme or layout changes etc.,

For this course, we will host the website on Github.

We will first need to setup version control using Git before we can do so.

Setup a Git repository

To start, initialize a git repository in the site directory using:

cd samplesite
git init

If you haven't already done so, add your name and email address to git configuration:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Github configuration

To proceed, you will need to

  1. Create an account at http://github.com.

  2. Add an SSH public key to your Github account. Please follow the instructions on github for generating SSH keys and adding it to your account.

    Warning

    Without this step, the following publishing steps will not work!

  3. You can verify that you have setup this correctly using the command:

    ssh -T git@github.com
    
    Hi user! You've successfully authenticated, but GitHub
    does not provide shell access.
    

    Note

    You might be prompted for the passphrase which you had used during the key generation.

Create repository on Github

On Github, create a new repository for the site using the following steps

  1. Create a new repository using the New repository button.

  2. For the Repository name, enter user.github.io where user is your user name on Github.

    For a user samplesite, this would be samplesite.github.io

  3. Click the Create repository button to create new repository.

    "Create repository on Github"

Adding a remote

Before we can publish our samplesite on Github, we will need to add a pointer to the repository we created on Github. This is called a remote. To do this:

cd ~/samplesite
git remote add origin \
git@github.com:samplesite/samplesite.github.io.git

Here we add the remote Github repository with the name origin.

Note

Please replace samplesite with your repository name.

Publish site

To push content in the "output" folder and publish the website on Github, we can use:

make github

Output:

(site)vl@lenovo:~/samplesite$ make github

pelican /home/vl/samplesite/content
-o /home/vl/samplesite/output
-s /home/vl/samplesite/publishconf.py

WARNING: Feeds generated without SITEURL set properly may not
be valid
Done: Processed 1 article(s), 0 draft(s) and 1 page(s)
in 0.19 seconds.

ghp-import -b master /home/vl/samplesite/output
git push origin master


Counting objects: 60, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (39/39), done.
Writing objects: 100% (60/60), 34.62 KiB | 0 bytes/s, done.
Total 60 (delta 16), reused 48 (delta 15)
To git@github.com:samplesite/samplesite.github.io.git
 * [new branch]      master -> master

After few minutes, the website will be available online at http://user.github.io. In this example, it is http://samplesite.github.io.

Note

According to Github, it might take upto ten minutes before the page is visible online after the first push. The next updates will be a lot faster.

Publishing the page on Github

Updating the site

Let's update the site by creating a new blog post.

Create a new file second-post.md in the content folder with the following text:

Title: This is our second blog post
Date: 2014-02-02 20:00
Slug: our-second-blog-post
Author: Your Name
Summary: This is our second blog post

This is our second blog post

Save second-post.md and load http://localhost:8000 in a browser to view the new blog post.

Push changes:

make github

After few minutes, load http://user.github.io in a browser.


If you have found this tutorial useful, you might be interested in the PDF version. Also includes code samples. Future updates are free.

Buy the eBook