I finally got post tagging working in Jekyll…made more difficult by some non-standard path choices. Possible footguns to consider…

  • Ultimately Jason Miller’s description of Long Qian’s process was the one I used. It didn’t work at first, so I went through and upgraded the files iteratively to match Jason Miller’s files
  • But still errors! What I learned is that the Jekyll header information (title, date, tag) must be lowercase or else they are ignored! Doh! It is easy to fix this using sed
    • This also fixes another minor bug that I had been experiencing, where the titles of blog posts displayed using only first letter capitalizations. Now I know that this is because jekyll was getting the name from the file name, and inferring capitalization. But once we switch this, it fixes the display, which is nice. No links should be broken by this change.
    • I’ve updated the Jekyll script accordingly
  • I had my site configured so that posts go to /blog/. But Jason’s doesn’t do this, which causes a bunch of file path issues on links. These can be fixed by modifying the _layouts and _includes paths acccordingly. If I were going to do this over, I would just clone Jason or Qian’s repo, delete all their posts, and just run with it. But I didn’t want to break links I shared with others, so I modified it. So I guess I could do it over again by using a time machine to retrieve my own repo now :-)
  • Both guys use a python script to create all the little tag files that are needed. But you can just do this on the command line (from within the _posts directory) on your local machine:
grep -h "^tags: " *.md | sed -e 's/tags: //;' | tr ' ' '\n'  | sort | uniq | while read name; do echo "---\nlayout: tagpage\ntitle: \"Tag: $name\"\ntag: $name\nrobots: noindex\n---\n" > "../tag/${name}.md"; done

(the robots line keeps them off the lawn of the index pages only) - You’ll need to run this periodically to update new tags that are present. I put an update_tags.sh script into _posts to make this easy.

  • I was getting a bunch of links to the tag files at the top of every page, which was annoying. It took me a while to figure out that this was being placed by the _includes/header.html and delete the resulting lines.
    • head.html is the non-displayed information (SEO details, metadata, previews, etc.)
    • header.html is the printed header at the top of the page