Setting Up Shop

With my choice of generator out of the way, it's time to get going. By the way, this mostly follows what is documented in the Pelican Quickstart. First things first

$ sudo apt install python-pelican

When that's done, it's simply a matter of running

$ pelican-quickstart

in a suitable location and answering the questions. For a brand new site holding my GitHub user pages, I set the URL prefix to https://paddy-hack.github.io and said yes to uploading with GitHub pages. Also noted that this will be my personal page. Next

$ git init
$ git add .
$ git commit

to record my starting point and I'm ready to add my first post below the content/ directory. Either reStructuredText or MarkDown will do. Just use a file extension that matches the markup used in the file. For reStructuredText that would be something like

$ editor content/2014-08-03-setting-up-shop.rst
$ git add .
$ git commit

Previewing And Publishing

Before publishing the site, let's take a preview, just to make sure everything is all right. No problem

$ pelican -s pelicanconf.py
WARNING: Feeds generated without SITEURL set properly may not be valid
Done: Processed 1 article(s), 0 draft(s) and 0 page(s) in 0.36 seconds.
$ (cd output; python -m pelican.server)

and fire up a web browser to look at http://localhost:8000/. The warning can be ignored for previews. There's a bit of tweaking still to be done but that's for later. Kill the pelican.server with Ctrl-C and publish for real

$ pelican -s publishconf.py
Done: Processed 1 article(s), 0 draft(s) and 0 page(s) in 0.36 seconds.

No warning this time. Good! The output/ directory now contains the site. This is what has to be pushed to GitHub on a master branch to make it my GitHub user pages. The simplest way to do so is by putting that directory in a repository of its own. The drawback of this approach is that it separates the source from the site. What I much prefer is to keep the site's source together with the site that gets pushed to GitHub. This is made possible and simple by GitHub Pages Import. It is just a single Python script with no other dependencies.

I have cloned the GitHub Pages Import repository and added a symlink to the script in ~/bin/.

$ cd ~/code
$ git clone https://github.com/davisp/ghp-import.git
$ cd ~/bin
$ ln -s ../code/ghp-import/ghp-import

Now I can use ghp-import to do the heavy lifting of tracking my site in a master branch while I maintain its source branch. Before running ghp-import for the first time, move the current master branch to a safe place: source. This is important because ghp-import destroys the target branch, like totally, utterly and completely.

$ git branch -m master source
$ ghp-import -b master output

Last step is setting my repository's remote and pushing.

$ git remote add origin https://github.com/paddy-hack/paddy-hack.github.io.git
$ git push origin master
$ git push origin source

That last line makes sure that everyone can follow the site in its source form as well.

Done!