I found out about some ways to organise content when using Jekyll today. The examples often contain pages and posts with tags and categories in the front matter (a header basically), but I had to search a bit to find out how to use them …

So the most basic thing about Jekyll is, that it processes any file having a front matter, a specific form of a header. This is mostly where one specifies “things” for the content. For example this page starts with the following front matter:

---
layout: post
title:  "Content Organisation and Presentation with Jekyll"
author: little big t
date:   2015-10-24 21:33:22
tags:
- jekyll
---

That’s in the opposite to files not starting that way, for examle pictures and alike. The layout specifies which template will be used and at the same time the “type” of the post. Templates are provided for pages and posts, wherein posts basically are for the blogging-style, while pages are for more static representations.

Those are treated differently:

  • Posts need to be put into the _posts folder and must follow a naming convention. For example this post has the name 2015-10-24-content-organisation-with-jekyll.md. All Posts get moved to a folder structure year/month/day/title and are named index.html after the build.
  • Pages seem to be all other files with such a front matter, i.e. not in the folder _posts and/or not following the naming convention. Pages from the top hierarchy are moved into folders with their name and also renamed to index.html.

You may have noticed the layout: post in the example above. It will still be treated like described for pages if not in the folder for posts. Also if you later use site.pages vs site.posts to query your content in ruby, it will be returned as page then. I guess one could add other types as well? But I haven’t verified that assumption, yet. Adding tags or categories in that front matter associates that data with the content. The example of this page associates the tag jekyll with this posts. You could use categories in the same way. Or any other variable you would like to set, far as I understood.

After that the data is there and needs to be used. So how to do that? Turns out this is rather easy. I did pages (in the opposite to posts) for tags and categories now, that should appear in the upper navigation bar. The code for the tags generates a list or array with the tags and then iterates over those and gathers all matching content. Output is done to HTML as you can see it on /tags.

 
<ul class="posts">
  {% capture tags %}
    {% for tag in site.tags %}
      {{ tag[0] }}
    {% endfor %}
  {% endcapture %}
  {% assign sortedtags = tags | split:' ' | sort %}
  {% for tag in sortedtags %}
    <h3 id="{{ tag }}">{{ tag }}</h3>
    <ul>
    {% for post in site.tags[tag] %}
      <li><a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
    </ul>
  {% endfor %}
</ul>

I highlighted the HTML here. The stuff escaped should be Ruby, which I had never touched before starting with this Jekyll btw. Pretty nice, guess I’ll play around more with such stuff in future … I took my quite some time to find out how to escape the escapes, i.e. to present that code as seen above. One can use a raw/endraw section analog to for/endfor as shown to achieve that btw. But I don’t know how to escape that now, so hope that was understandable ;) But at least I can use the tags in a sensible way now. Not sure how to best combine tagging with categories, yet.

I then also fiddled around with the layout a bit. The hightlighting function seems to recognise how to highlight, if you start the section with something like #!/usr/bin/python3. For the shell-snippets I often use in documenations that seemed not appropriate, but I had a hard time finding out how to tell manually what I want. The short names given in the lexers seems to be what one can add as a parameter to the highlight section. So I now use {% highlight console %} for the snippets.

Clearnet-Links I used as sources are:

  • http://stackoverflow.com/questions/24102498/escaping-double-curly-braces-inside-a-markdown-code-block-in-jekyll
  • https://stackoverflow.com/questions/1408824/an-easy-way-to-support-tags-in-a-jekyll-blog
  • http://christianspecht.de/2014/10/25/separate-pages-per-tag-category-with-jekyll-without-plugins/
  • http://pygments.org/docs/lexers/