How to make a blog like this

Marton Trencseni - Thu 07 January 2016 - Meta

Getting your own blog like this is really easy, no server hosting nedded. There are two ingredients:

  • Github Pages
  • the Pelican static blog generator

Github Pages

Suppose your username on github is mtrencseni. Create a repo called mtrencseni.github.io. Here's mine: https://github.com/mtrencseni/mtrencseni.github.io. Anything you put in there will be served up at http://mtrencseni.github.io. Try it out for youself, put in an index.html containing Hello world.

Your own domain name with Github Pages

I wanted to use my existing domain name bytepawn.com. Github is so nice, they support this. Put a file called CNAME into your repo. Here's mine: https://github.com/mtrencseni/mtrencseni.github.io/blob/master/CNAME

This tells Github to expect requests for this domain. What's left is to tell your DNS provider to use Github. (My registrar is Internet.bs, so much better than Godaddy.) Create an A record that points to 192.30.252.153, this is a Github IP address. That's it. For bytepawn.com it looks like this:

$ dig bytepawn.com

; <<>> DiG 9.9.5-3ubuntu0.5-Ubuntu <<>> bytepawn.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 34353
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;bytepawn.com.                  IN      A

;; ANSWER SECTION:
bytepawn.com.           600     IN      A       192.30.252.153

;; Query time: 19 msec
;; SERVER: 172.17.0.1#53(172.17.0.1)
;; WHEN: Thu Jan 07 21:36:09 UTC 2016
;; MSG SIZE  rcvd: 57

Generating a static blog

Github will serve static content from your repo, it doesn't run any scripts. So you need to use a static site generator and serve up the generated pages. Fortunately, there are many. The two biggest ones are Jekyll for Rubyists and Pelican for Pythonistas. I'm a Python guy, so I use Pelican. The Pelican quickstart doc explains how to generate an empty blog. Basically:

$ pip install pelican markdown
$ cd blog
### this is https://github.com/mtrencseni/blog locally
$ pelican-quickstart
$ vi contents/my-first-article.md
### see the docs what an article should look like
$ pelican content
### generates static files in the `output` dir
$ cp -R ouput/* ../mtrencseni.github.io
$ cd ../mtrencseni.github.io
$ git add * && git commit -m "Working :)" && git push
### it's live!

Simply copy the contents of Pelican's output directory into mtrencseni.github.io, and that's it.

Getting a theme for Pelican

The default theme is kind of crappy looking. Fortunately, there's a ton of free themes for Pelican at http://www.pelicanthemes.com/. Here's the github repo for all those themes: https://github.com/getpelican/pelican-themes. I picked Flex, and did some very minor customization on it. Getting Pelican to use a theme is simple: put a line like THEME = 'flex' into your pelicanconf.py, where flex is the directory containing the theme you picked. Here is mine: https://github.com/mtrencseni/blog/blob/master/pelicanconf.py

Putting it all together

I have a repo https://github.com/mtrencseni/blog which contains the source of the blog. It's a copy of Pelican, with my articles in the content directory, and a (customized) copy of the flex theme in the flex directory.

I use Pelican to generate the static output, and then that gets pushed to https://github.com/mtrencseni/mtrencseni.github.io

I customized the Makefile to automate this. Here's mine: https://github.com/mtrencseni/blog/blob/master/Makefile. It contains targets for clean, output, preview and publish. preview uses the built in Python webserver to serve up the static site on localhost:8080 for testing. publish git commits to the mtrencseni.github.io repo.

That's it. You can get up an running within a day.

Links

blog pelican