Blogging with Github + Pelican

Wed 20 August 2014

Filed under Python

Tags pelican python

In the name of fun and procrastination, I have moved my irregular internet musings to this Pelican powered github site.

Pelican is a neat little static site generator, similar to Jekyll, but using Python (my preferred language). Pelican generates content from markdown, reStructuredText or html files, the latter allowing the publishing of IPython notebooks and .org files, both of which I use extensively.

Github pages hosts websites directly from code repositories, an appealing idea given Github already hosts all my publicly available code.

I faced one critical conceptual stumbling block: when making a User page (user.github.io) the processed html lives in the main branch of the git repository, while the source should live somewhere else, such a second branch called source. Thankfully, this post cleared up much of my confusion. Below are my abbreviated instructions for *nix systems:

Install Pelican

If Pip is not already on your system, install it. Directions.

To install Pelican, you can use a virtualenv if you prefer or simply use the --user flag. The ghp-import is used by the Pelican MakeFile to push the output folder to the main branch. To create content with Markdown, you should also install the Markdown library.

pip install --user pelican ghp-import markdown

Create the Github repository

If not already created, create the repository by following the instructions 1-2 here, then

cd YOURUSERNAME.github.io

Generate a skeleton pelican project

Add a skeleton pelican project to the source branch

git checkout -b source
pelican-quickstart

Create some content

Content is added to the content folder, see the pelican documentation for formatting details.

echo -e "Title: Example\nDate: 1970-01-01\n Hello, Internet!" > content/examplepost.md

Preview

make html
make serve

Point your browser to localhost:8000.

Publish

make github

Done. In a couple minutes, your website should be visible at YOURUSERNAME.github.io.

From here, peruse the Pelican documentation for themes and other settings.


Comments


Creative Commons License
Fasciculus by Kyler Brown is licensed under a Creative Commons Attribution 4.0 International License. Powered by Pelican, Twitter Bootstrap, Font Awesome, Font Awesome More