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.
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:
Once you answer all questions Pelican will create the files and folders shown below:
yourproject/ ├── content │ ├── (pages) # These folders are not auto-created │ ├── (posts) │ └── (images) ├── output ├── develop_server.sh ├── fabfile.py ├── Makefile ├── pelicanconf.py # Main settings file └── publishconf.py # 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
The images for your site or blog should be located in the
You also need to tell Pelican that this folder holds your static content and images by adding the line below to ‘pelicanconf.py’ :
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
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:
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
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
One of the best free places to host your static site for free is 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 http://www.dot.tk - 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:
184.108.40.206 220.127.116.11 18.104.22.168 22.214.171.124
Here are other ways to point your domain to github pages.