(since that's what I'm now using)

  • Pagination - It is actually documented, and this site is a great example of how to do it, BUT (and it is a big BUT), basically you can either have categories OR pagination. I opted for categories and then adding in the ability to filter the archive page by category so there was still someway to get all the posts in a category.
  • Nested for loops - don't seem to work in Liquid. I was trying to get all the categories of a post as class names, but couldn't get it to work. However, me being stupid, there was a much easier way to do this.
  • Markdown processors - I'd read about there being different markdown processors, Rdiscount, Makuru, etc and wondered why? Until I tried my site, that is. When you've things like having markdown files that use html elements, Rdiscount will process this fine, Makuru will fall over.
  • Liquid syntax conflicts - (An aside: I actually like the Liquid markup syntax, it's pretty cool). I had a blog post about Wolfram Alpha and a link to a matrix calculation that used double curly brackets for the matrix and got the error "Liquid Exception: Variable '{ {1%2C1%2C3}' was not properly terminated with regex p: /}}/" in the page. I've not figured out anyway to avoid this, I.e. escape curly brackets from being processed. I just had to use square brackets instead.
  • The mystery of post vs pages - After awhile you figure this out, and you do clever things (I felt clever, anyway) like use both in the same include. At least you think you'd figured it out, until you realise the page's aren't getting parsed by Markdown. Turns out you have to just use content, even though page.title and post.title work as expected. Entirely weird.