Introduction to Pelican (1) Creating a Personal Web Page

Overview

This is my first time to use GitHub and Pelican to creating a personal website (blog page). The whole progress was made on Mac OS X, although I tried on the Windows 7 first. It proved it would be much more convenient if you tried on Mac.

Preparation

If this is your first time to use terminal, it will be better to get some basic knowledge about it. Google is always your good teachers and friends! Github should also be learnt if you do not want to be massed with the git codes. Here are some recommended websites:

Terminal

• Introduction to the Mac OS X Command Line
• Terminal Cheatsheet for Mac (basics)

GitHub

• GitHub教程 (zh-CN)
• git-scm (En)
• git-scm (zh-CN)

You need to register a GitHub account before the Pelican Setup. A repository named username.github.io should also be created. To reduce trouble, README file is not recommended to be created for the beginner of GitHub. They will be used in Chapter Pelican Setup.

Configure local environment

You will also need to install some basic package before this tutorial. I presume most latest Mac OS X come with Python.It may require administrator password for $ sudo.

1. Install pip:

   $ sudo python get-pip.py
   

2. Install Pelican (most important) and Markdown (to support .md):

   $ sudo pip install pelican
   $ sudo pip install markdown
   

Some people may have ValueError because of the unicode. You can check weather your terminal environment is in UTF-8 by $ locale. If not, you can temporarily change it by:

$ export LC_ALL=en_US.UTF-8
$ export LANG=en_US.UTF-8

To change it persistently, you need to add above command in ~/.profile.

Pelican Setup

Create a local folder for the blog:

$ mkdir blog #you can decide the name you want
$ cd blog

Initialise the blog:

$ pelican-quickstart

Just follow the steps to initialize:

$ pelican-quickstart
Where do you want to create your new web site? [.]
What will be the title of this web site?
> <GitHub username> e.g. abc123
Who will be the author of this web site?
> <name you want to use> e.g John
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://username.github.io
Do you want to enable article pagination? (Y/n)
How many articles per page do you want? [5]
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)

If you want to take a look of the tree structure of the generated files, please install Homebrew and tree:

$ ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" 
$ brew install tree

Then you can use command $ tree to read the folder like this:

blog/
├── content               
├── output               
├── develop_server.sh    
├── Makefile             
├── pelicanconf.py       
└── publishconf.py

Writing articles

The default folder for writing articles are set in the /blog/content, which can be configured in pelicanconf.py if you want. In this tutorial, the article (.md file)is put in content. Pelican needs metadata like Title(must), Date (optional) and other optional information for smart settings. For example:

Title: Introduction to Creating GitHub Pages with Pelican
Date: 2015-09-13 21:07
Modified: 2015-09-13 21:07
Category: Coding
Tags: GitHub,Pelican,Markdown
Slug: Blog
Authors: Joe
Summary: Creating Blog

Here is the content you want to write in Markdown style....

To generate the site locally, you can run command:

$ make devserver

It serves your site to http://localhost:8000. You can preview the website locally first.

Or you can just generate html without testing

$ make html

No matter which method you choose, some .html file will be generated in folder output. To debug easily and for the future convenient, I recommend to new a folder under blog, e.g. /blog/gitblog and copy the files in outputto this folder. Why? I will explain later.

Upload the pages

Since all the html files are prepared, we only need to upload them to our GitHub. These part should be done after you have a basic knowledge of GitHub. If you have already created README file in GitHub, you may need to add $ git pull origin master before $ git add ..

$ cd gitblog
$ git init
$ git remote add origin https://github.com/username/username.github.io
$ git add .
$ git commit -m "first commit"
$ git push -u origin master

You may need to input GitHub username and passward if you do not use SSH key introduced in Chapter GitHub. If no error, you can visit you blog by username.github.io.

Modify and update pages

The reason to create another folder instead using output to upload pages is that every time you use $ make html, output will be replaced with new files. Thus, it would be better to copy the files from output into gitblog before uploading.

Here is some commands for delete and update files:

$ git rm ×××.html
$ git add . 
$ git commit -m "some message"
$ git push -u origin master

Summary

This article is only the introduction of setting up a personal blog by using GitHub and Pelican. Since this is my first time to use it, some condition my not be covered. Please comment below if there is any error.