Transistors, transistors everywhere...

Random musings about Python, SystemVerilog, digital design and DSP.

View on GitHub
9 April 2021

Customizing your Jekyll blog in Github: support for tags (without external plugins), Latex math formulas, comments section

by Alberto Garcia

tags jekyll blog

Setting up a blog in Github with Jekyll is a reasonably painless experience (thanks in part to the comprenhensive Github documentation). However, there are a few features that do not come ‘out of the box’:

In this post, we’ll try to fix these issues…

Tag support (without external plugin dependency)

This solution is based on an original post at Christian Specht’s site. I’ve added a small Python3 script that automates the task of regenerating tag index pages, and a small Liquid snippet to add to your post layout that will display links to the tag indexes that are used in the current post page.

---
layout: post
title:  "Customizing your Jekyll blog in Github: support for tags (without external plugins), Latex math formulas, comments section"
date:   2021-04-09 13:06:03 +0200
categories: jekyll update
tags: jekyll blog
---

For example, this post has been tagged with jekyll and blog.

---
layout: default
---

<h1>{{ page.tag }}</h1>

<ul>
{% for post in site.tags[page.tag] %}
  <li>
    {{ post.date | date: "%B %d, %Y" }}: <a href="{{ post.url }}">{{ post.title }}</a>
  </li>
{% endfor %}
</ul>

This layout will be used for tags index pages: each one will show links to all the posts that contain the tag.

{% if page.tags %}
  <small>tags 
  {% for tag in page.tags %}
    {% for site_tag in site.tags %}
      {% if tag == site_tag[0] %}
        <em><a href="/tags/{{ tag }}/index.html">{{ tag }}</a></em>
      {% endif %}
    {% endfor %}
  {% endfor %}
  </small>
{% endif %}

This will show the tags you’ve used for your post, wherever you placed it in the layout (In this post, they are located between the Title-author and the main content)

#!/usr/bin/env python

# creates index pages for the posts tags in ./tags
# to work, it requires a tagpage.html layout in ./_layouts

import os
import glob

posts = glob.glob('./_posts/*.markdown')
site_tags = set()

for post in posts:
    print(f'-- {post} tags:')
    inside = False
    front_matter = []
    with open(post, 'r') as f:
        for line in f:
            if '---' in line and not inside:
                inside = True # next line is front matter
            elif '---' in line and inside:
                break #front matter finished
            elif inside:
                front_matter.append(line)


    tags = []
    for line in front_matter:
        if 'tags:' in line:
            tags = line.strip().split()[1:]
            print('  ' + ' '.join(tags))
            break
    site_tags = site_tags | set(tags)

for tag in site_tags:
    os.makedirs(f'./tags/{tag}', exist_ok = True)
    with open(f'./tags/{tag}/index.html', 'w') as f:
        s  =  '---\n'
        s +=  'layout: tagpage\n'
        s += f'tag: {tag}\n'
        s +=  '---\n'
        f.write(s)

print('-- tags refreshed.')
>> python refresh_tags.py

This script will create a ./tags folder, where all your tag index pages will be stored (like this: ./tags/tag_name/index.html)

Adding Latex Math formulas with MathJax

Add the following to the <head> section of _layouts/default.html:

    <script type="text/x-mathjax-config">
      MathJax.Hub.Config({
	  tex2jax: {
	      inlineMath: [['$','$'], ['\\(','\\)']],
	      processEscapes: true
	  }
      });
    </script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>

You can add then Latex formulas in your markdown: e.g.$V^2 + D_i$ will render as $V^2 + D_i$

Comments section in your posts with utterances:

utterances allows you to add comments in your post that are stored as GitHub issues. People wanting to comment on your posts will need a GitHub account (which is almost a feature, rather than a drawback :blush: ). Setup couldn’t be easier: just add the following script call to your ./_posts/post.html layout, where you want the comment section to be (change your username/reponame to your Github user name and the repo name of your site):

<script src="https://utteranc.es/client.js"
        repo="username/reponame"
        issue-term="pathname"
        label="💬comment"
        theme="github-dark"
        crossorigin="anonymous"
        async>
</script>

See their site for more information on configuration options.