In this articel I’ll show you how to create a static html site with Pelican and host it for free at GitHub Pages.

Pelican is a static site generator, written in Python, that requires no database or server-side logic. Pelican

Installing Pelican

The easiest way to install Pelican is using pip, use the command below to install it along with the Markdown module:

$ sudo pip install pelican Markdown

Initialize your site

Once Pelican has been installed, you can create a skeleton project via the pelican-quickstart command, which begins by asking some questions about your site:

$ pelican-quickstart

Once you answer all questions Pelican will create the files and folders shown below:

├── content
│   ├── (pages)          # These folders are not auto-created
│   ├── (posts) 
│   └── (images)
├── output
├── Makefile
├──       # Main settings file
└──       # Settings to use when ready to publish

Your site content should be placed in the content folder. If you plan to create a blog, you’ll need to create a folder named posts in the content folder, if you need just static pages that are not chronological create a folder named pages.

The images for your site or blog should be located in the content/images folder.

You also need to tell Pelican that this folder holds your static content and images by adding the line below to ‘’ :

STATIC_PATHS = ['images']

You can have more than one folder for static content and you can also pick another location.

Building your content

To create a new page or blog post you need to create a file in the pages or posts folder. This file needs to be ending in .md, .markdown, .mkd, or .mdown and contain text formated with markdown syntax.

Your file may contain the following meta-data (not all values are mandatory)

Title: My post title
Date: 2018-02-03 11:21
Modified: 2018-02-05 17:30
Category: Python
Tags: pelican, publishing
Slug: my-blog-post
Authors: John Smith, Hristo Jelev
Summary: Short version for index and feeds

This is the content of my first blog post.

To add images to your content use the markdown below:

![Alt text](images/filename.jpg)

Add link with target=”_blank”:


If you are not familiar with markdown syntax look at markdown cheat sheet

Once you create all the pages and articles its time to generate your site html.

Generating your site HTML

To generate your site, go to your project root folder and run the command below:

$ pelican content

You can also use:

$ pelican -r

This command will regenerate your site each time a change is detected.

When the generation is complete all the files (html, images, css and maybe others) for your new site will be located in the output folder.

Preview your site

Its useful to view your site before uploading it to your hosting. To run a local web server use one of the commands below.

For Python 2, run:

$ cd output
$ python -m SimpleHTTPServer

For Python 3, run:

$ cd output
$ python -m http.server

Once you start the web server you can preview your site at http://localhost:8000/.


One of the best free places to host your static site for free is Github Pages

Github Pages

On github pages you’ll find detailed instructions how to upload your site with git. If you don’t have git installed you can install it with:

$ sudo apt-get install git

Once your site is uploaded to github pages its url will look like this

You can change this by adding a custom domain to your github repository. If you don’t have a domain name you can get one for free from - they offer five domain extension for free (.tk, .ga, .ml, .cf and .gq).

First add your domain name to your new github repository by following these instructions.

Then point your custom domain to the following IP addresses:

Here are other ways to point your domain to github pages.