Jekyll on App Engine with beautiful URLs

For my project Waterglass I host a static Jekyll blog on Google App Engine. And of course I want beautiful URLs like /blog/8-cat-pics-that-made-me-smile – but that’s not as automatic on App Engine as on other servers. So here is how you do it.

Jekyll can build your blog having nice URLs. It does this by throwing an index.html file inside your directories. E.g. there is /blog/index.html and /blog/8-cat-pics-that-made-me-smile/index.html. This doesn’t work on App Engine out of the box because it doesn’t have the concept of index documents for static directories. But we can use regular expressions inside URL handlers in the app.yaml file to fake them.

Faking index documents on Google App Engine

Let’s say our blog’s URLs should have this structure: /blog/2014/this-is-the-article-title

We’ll just have to generalize this a bit to match any year and any title and add this handler to our app.yaml:

- url: /blog/(\d{4})/(.*)
  static_files: static/blog/\1/\2/index.html
  upload: static/blog/.*

The url line contains a regex which has two groups. The first matches the year (four digits) and the second matches the remaining characters. In static_files we use these two groups (\1 and \2) to construct the path to the index.html we want to return when someone hits a matching URL. upload finally tells App Engine which files to upload to the server – in our example everything inside the blog directory.

Now you should also add a handler for /blog – which is really straightforward.

- url: /blog
  static_files: static/blog/index.html
  upload: static/blog/index.html

Voila, you now have beautiful URLs with your Jekyll blog on App Engine.