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!
An outline of what we will do
- Install programs required for building and hosting the website - Python, Pelican, virtualenv, Git etc.,
- Learn how to create and work with virtual Python environments.
- Build a basic site structure and add pages and blog posts.
- Host the website online on Github. You can also upload the generated files to your web host using FTP or other means.
The basic requirement for this course is an installation of Ubuntu Linux.
These steps have been tested on Ubuntu 14.04 LTS.
Some options if you do not have Ubuntu installed
You can download the latest version for free from the website - http://www.ubuntu.com/download/desktop.
Another option is to install the downloaded Ubuntu ISO in a virtual machine like Virtualbox.
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:
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
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:
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:
Within the virtualenv, you can install additional Python modules or run scripts installed by these modules.
To exit, type:
You will be returned back to the prompt.
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.
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:
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
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:
Setup a basic structure for the site using the pelican-quickstart command:
We will be asked a series of questions for the inital site configuration.
You can press ENTER to accept the default value for any option.
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?  > 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
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
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.
To stop watching for changes, type:
vl@laptop:~/samplesite$ make stopserver
You can also generate the site manually using:
Afterwards, you can serve the generated content using:
To stop, press CTRL+C.
We can now start adding new content to the website.
The site does not have any content yet. Let us see how we can add a new page and a new blog post.
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:
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.
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.
You can assign posts to a category using Category:
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 "firstname.lastname@example.org" git config --global user.name "Your Name"
To proceed, you will need to
Create an account at http://github.com.
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.
Without this step, the following publishing steps will not work!
You can verify that you have setup this correctly using the command:
ssh -T email@example.com Hi user! You've successfully authenticated, but GitHub does not provide shell access.
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
Create a new repository using the New repository button.
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
Click the Create repository button to create new repository.
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 \ firstname.lastname@example.org:samplesite/samplesite.github.io.git
Here we add the remote Github repository with the name origin.
Please replace samplesite with your repository name.
To push content in the "output" folder and publish the website on Github, we can use:
(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 email@example.com:samplesite/samplesite.github.io.git * [new branch] master -> master
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.
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.
After few minutes, load http://user.github.io in a browser.