Getting Markdown and Git to work in Pelican

get pelican

Ok! so this was a fun experiment. I wanted to be able to run git push and have everything be published automagically to the website.

While I am posting this first blog post I am still testing out some kinks and getting everything to work correctly. And as I say that... everything works... except pelican doesn't default to using .mkd files. Silly vim-markdown not recognizing the .md suffix.

OK here is where I got everything working correctly(and I broke it)

Setting up the pelican user!

To keep everything clean on my server and also to prevent me from having to install a whole shitton of extra python packages, I am just using a virtualenv and managing everything from a seperate user. In my pelican users home directory, there are 3 extra directories.

Blog Virtual Environment

First off is ~/blogenv/. In this directory we have our virtual environment. Because I am using Arch Linux, and we default to python3, I was very happy to see pelican is compatible with python3. Once you have whatever python-virtualenv package your distribution comes with, just make the virtual environment and install pelican.

virtualenv ~/blogenv
source ~/blogenv/bin/activate
pip install -e git://

If you are wanting to use markdown, you will need to pip install it as well.

pip install Markdown

I prefer to use the git repository for pelican, feel free to use the version from pypi. A nice tip, since we are only going to ever use this user for that virtual environment is to just add source ~/blogenv/bin/activate in your ~/.bashrc so that we always get the environment when using bash.

Start blog

Next we need to setup our blog environment. This one is really simple, just run the pelican-quickstart command and answer all the questions that it asks.

pelican-quickstart -p ~/blog

If you really wanted, you could stop here. You just write your blog posts in the content directory under ~/blog. Once you have written something, run make in ~/blog and your html files will be put in ~/blog/output. Then just host the blog with nginx or an equivalent HTTP server.

server {
    listen 80;
    root /home/pelican/blog/output;
    index index.html;
    location ~ ^/feeds {
        autoindex on

Setting up git

If you are like me, you like it when things are automated. This is where git comes in to keep track of your blog posts and files. This way we only have to keep track of a small number of files and don't have to worry about the rest of the pelican files if we don't want.

Start out with making your blog git repository on your localmachine and initialize it.

mkdir ~/gitrepos/blogposts
cd ~/gitrepos/blogposts
git init

After this you will want to go ahead and copy over your from the ~/blog directory on the remote device to your local git repository. Now git add it.

git add
git commit -m "First Commit -> Starting new blog!"

Now we need to go back to the pelican user on your remote machine with the pelican subdirectory. I personally kept with the blog directory naming theme and initialized a bare repo for my blog.

mkdir ~pelican/bloggit
cd ~pelican/bloggit
git init --bare

Now we can go ahead and setup out githook that is going to do all the work for us. Copy the following into ~/bloggit/hooks/post-update.

#!/usr/bin/env bash
source ~/blogenv/bin/activate
GIT_WORK_TREE=/home/pelican/blog git checkout -f
pushd ~/blog
make publish

Be sure to chmod +x the file as well.

I know what you are thinking! Why do we have to source bin/activate in the git hook if we are already sourcing it in .bash_profile? Well, this script won't read .bash_profile. There are ways to make it read that file, such as adding --login after the bash call, but this is rather messy and and one extra line isn't a big deal.

Now, back on your local machine, lets make a markdown file to publish our first blogpost. In your git repository, make a contents directory and write a blog post. Here is an example if you don't want to spend the time right now.

From the pelican documentation

Title: My super title
Date: 2010-12-03 10:20
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Author: Alexis Metaireau
Summary: Short version for index and feeds

This is the content of my super blog post.

Place this in a file ending with .md for your git repository. We now need to setup the remote git repository and push to it.

git remote add website
git remote update
git push -u website master

This should generate the blog posts and you should be able to use the same nginx.conf server from above.

I am a bit weird about my nginx configurations and /home

Now when I was writing this post I removed a few bits and pieces from my actual setup, just beacuse I am peculiar. The Makefile for pelican recognizes the environment variable OUTPUTDIR for where you want output set to... so I set it to /srv/http/

#!/usr/bin/env bash
source ~/blogenv/bin/activate
GIT_WORK_TREE=/home/pelican/blog git checkout -f
make -C ~/blog OUTPUTDIR=/srv/http/ publish

Again, be sure to chmod +x the hook.

I also wanted to use vim-markdown, and I use pathogen, so I just cloned the git repo into ~/.config/vim/bundle (yes .config ... it is a long story). Because vim-markdown only uses .mkd suffix, I had to add the following to

MARKUP = ("mkd",)

Don't forget the , because python is expecting a list.


I Hope to be doing a lot more of these blog posts now that I can remove the vim blogit plugin because Wordpress truely sucks.


comments powered by Disqus