How To Use Tags And Categories On GitHub Pages Without Plugins

GitHub Pages service is just awesome!

And with the jekyll integration it even get’s more awesome! :D

But there are some limitations of this big automated system:

As you may know:

  • no tag / category plugins are (currently) available.

Sad.. But that was something I really wanted to have!

So I built my own Data-Template-NoPlugin-System and it works.

You can see a live demo on this page.

Here is a little guide how to implement it yourself:

  1. add some template logic on top of your post layout

    {% assign post = page %}
    {% if post.tags.size > 0 %}
        {% capture tags_content %}Posted with {% if post.tags.size == 1 %}<i class="fa fa-tag"></i>{% else %}<i class="fa fa-tags"></i>{% endif %}: {% endcapture %}
        {% for post_tag in post.tags %}
            {% for data_tag in site.data.tags %}
                {% if data_tag.slug == post_tag %}
                    {% assign tag = data_tag %}
                {% endif %}
            {% endfor %}
            {% if tag %}
                {% capture tags_content_temp %}{{ tags_content }}<a href="/blog/tag/{{ tag.slug }}/">{{ tag.name }}</a>{% if forloop.last == false %}, {% endif %}{% endcapture %}
                {% assign tags_content = tags_content_temp %}
            {% endif %}
        {% endfor %}
    {% else %}
        {% assign tags_content = '' %}
    {% endif %}
    
  2. place the generated tag content wherever you like inside your post layout

    <p id="post-meta">{{ tags_content }}</p>
    
  3. create a blog_by_tag layout

    <h1>Articles by tag :{{ page.tag }}</h1>
    <div>
        {% if site.tags[page.tag] %}
            {% for post in site.tags[page.tag] %}
                <a href="{{ post.url }}/">{{ post.title }}</a>
            {% endfor %}
        {% else %}
            <p>There are no posts for this tag.</p>
        {% endif %}
    </div>
    
  4. annotate your post entry front-matter block as usual:

    ---
    layout: post
    title: How To Use Tags And Categories On GitHub Pages Without Plugins
    category: programming
    tags: [github, github-pages, jekyll]
    ---
    
  5. for every used tag you have to add an entry inside your _data/tags.yml

    - slug: github-pages
      name: GitHub Pages
    
  6. for every used tag you have to add an empty template - e.g. blog/tag/github-pages.md

    ---
    layout: blog_by_tag
    tag: github-pages
    permalink: /blog/tag/github-pages/
    ---
    

For a more complex implementation and categories: check out my repository


Updates (Feb. 12, 2015):

Updates (Apr. 4, 2015):

  • Switched to absolute permalinks (which is forced by jekyll 2.0+)

Updates (June 14, 2015):

  • Róbert Papp suggested (here) a restructuring of the data content so you can simplify the lookups. Thanks!

    • before

      - slug: github-pages
        name: GitHub Pages
      
      {% for post_tag in post.tags %}
          {% for data_tag in site.data.tags %}
              {% if data_tag.slug == post_tag %}
                  {% assign tag = data_tag %}
      
    • after

      github-pages:
        name: GitHub Pages
      
      {% for post_tag in post.tags %}
          {% assign tag = site.data.tags[post_tag] %}
      

Updates (May 18, 2016):

Posted in Programming with : GitHub, GitHub Pages, Jekyll