Installing Pelican on Github Pages using Cloudflare SSL (Part 1)

Posted on Mon 16 April 2018 in technical • 4 min read

It just wouldn't be done to move to a new blogging platform without describing how it went, and what I did to get it working.

Resources

Most of the steps I have taken here have been shamelessly copied from the following sources, albeit with some slight modification.

Local environment

This blog was set up on a 13" 2016 Macbook Pro with that awful keyboard. I use Homebrew for all the stuff that helps make the Apple's BSD environment a bit more useful, including updating my Python installation to v3. My editor of choice is Sublime Text, and I use Dropbox as a way of preserving my virtual environments. (More on that later)

Github setup

The first thing to do is to create a new repository in GitHub to hold your site. The repository needs to be named: username.github.io, where username is your GitHub username, or it won't work.

GitHub repository name

Local setup

Now that you have set up the repository, you'll need to prepare your local environment. I keep the site in Dropbox as additional backup/version control, but you can put it wherever you like. Clone the repository into your local environment.

$ cd path/to/where/you/want/virtualenv/to/live
$ git clone https://github.com/<USERNAME>/<USERNAME>.github.io.git
$ cd <USERNAME>.github.io/

Now that you're in the correct directory, you'll need to check the source out locally. Github prefers to serve the site from the master branch, so create a new branch, called source, (thanks, Renata, via Adrien Leger. Seriously, NOBODY else mentions this, and it tripped me up.).

$ git checkout -b source

Create and activate a new virtual environment inside the .github.io directory you're currently in, (if you've been following above) or navigate to it again to issue the commands.

$ virtualenv venv
$ source venv/bin/activate

Your prompt should look similar to the following. (Note the addition of the name of the virtual environment in brackets before your prompt)

(venv) $

Now that you're in your virtual environment, it's time to install the relevant python packages needed for Pelican. I use Markdown to write my posts, and so need to install the markdown plugin as well.

$ pip install pelican markdown ghp-import

Once all the relevant packages are installed, it's useful to freeze so you can bring them back if necessary.

$ pip freeze > requirements.txt

Once you've done all that, you can instantiate the site using the pelican-quickstart command, which asks you some questions and sets things up accordingly. We'll be using GitHub Pages here, and you'll also need to take care of the following questions:

  • What is your time zone? Mine is Europe/London, but you can find the list of values on Wikipedia. The format must be exactly as listed.
  • Do you want to generate a Fabfile/Makefile to automate generation and publishing? (Y/n) Answer: Y.
  • Do you want to upload your website using GitHub Pages? Answer: Y.
  • Is this your personal page (username.github.io)? Answer: Y.

So, being mindful of the required answers to the questions above, you can now set up Pelican using the quickstart command.

$ pelican-quickstart

Create a first post

Now that everything is installed, it's time to create a first post. Fire up your editor of choice, and create a new file called firstpost.markdown in the content folder under the USERNAME.github.io folder.

Your folder structure should now look similar to the following:

username.github.io
    |--content
    |  |___firstpost.markdown
    |___venv
    |   |___...
    |___requirements.txt
    |___...

Each post (markdown file) needs to be described by metadata, which provides some useful information for segmenting on category, date etc. The format is as below.

Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds

This is the content of my super blog post.

It might be worth adding a text expansion rule or a snippet, to aid in this process, as you'll need this every time a new post is added. My Sublime snippet is below:

<snippet>
  <content>
Title: $1
Date: $2
Modified: $2
Category: $3
Tags: $4, $3
Slug: $5
Authors: Pierre
Summary: $6

$7
  </content>
  <!-- Optional: Set a tabTrigger to define how to trigger the snippet -->
  <tabTrigger>blogpost</tabTrigger>
  <!-- Optional: Set a scope to limit where the snippet will trigger -->
  <scope>text.html.markdown, text.html.markdown.multimarkdown</scope>
</snippet>

Once you've saved your new file, you can test it locally by running the following:

(venv) $ make html && make serve

This will create a local web server on your machine, which you can test by browsing to localhost:8000.

Picture of first post

If you're looking at your post, well done. It's working as expected.
This won't look the same as yours by default, as I've already changed my theme. (We'll get to that later)

In Part 2, I'll talk about config options, cloudflare setup and pushing content to live., (while testing locally).