Customizing the Jekyll Theme
Tags: development, jekyll, github, markdown
Published: 2022-12-27 17:30:23

---
title: Customizing the Jekyll Theme
published: true
date: 2022-12-23 00:00:00 UTC
tags: Development,jekyll,GitHub,markdown
canonical_url: https://chris-ayers.com/2022/12/23/customizing-the-jekyll-theme
series: Migrating To GitHub Pages
---

I haven’t done a lot with jekyll in the past, but I’m a big fan of MarkDown everything. For me that usually means I’m taking notes in markdown [Obsidian](https://obsidian.md%5D), doing diagrams in mermaid in Azure DevOps or [https://mermaid.live/](https://mermaid.live/). I’ve even started turning my talk slides into MarkDown with a tool called [MARP](https://marp.app/).

Understanding when I use standard MarkDown or some sort of templating language (jekyll uses Liquid) has been fun. I’ll do something in html or MarkDown, then find out that Jekyll or my theme already has helpers to render that (like gists, videos, and figures). Sometimes rendering more advanced things takes a little tweaking of Jekyll and the theme.

Lets take Mermaid for example. If I want to render mermaid, it won’t work out of the box with jekyll or my theme. I need to tweak things and inialize things manually. If I want to render a graph, this won’t work out of the box.

```
    '''mermaid
    graph TD;
        A-->B;
        A-->C;
        B-->D;
        C-->D;
    '''

```

So to make it work, I had to override the base theme. To start, I looked at the themes layouts. They live in the \_layout folder of the theme [here](https://github.com/mmistakes/minimal-mistakes/tree/master/_layouts). These are the base structure of a page and most reference either Archive or Default.

![Theme layout for posts](https://chris-ayers.com/assets/2022/12/minimal-mistakes-layout-posts.png)
_Theme layout for posts_

![Theme layout for archive](https://chris-ayers.com/assets/2022/12/minimal-mistakes-layout-archive.png)
_Theme layout for archive_

Fortunately Archive also refers to Default so I can focus my changes there if I want to override it.

![Theme layout for default](https://chris-ayers.com/assets/2022/12/minimal-mistakes-layout-default.png)
_Theme layout for default_

Looking at this file, there are a few includes defined. One of which is the footer/custom.html and one is scripts.html. I looked through the scripts.html and it has a lot of logic I’d prefer not to duplicate. I’m alreadying using the header-custom file to define some css/scripts. I’ve found Mermaid needs its init to run in the body, so i’ll probably want to leverage the footer/custom.html for this. It’s an empty file in the theme, making it any easy choice to override.

I created a footer folder in my local project \_includes and a custom.html file. I added some simple logic to only add the mermaid logic if I added a `mermaid:true` flag at the top of the page.

![Custom footer logic for mermaid](https://chris-ayers.com/assets/2022/12/custom-footer.png)
_Custom footer logic for mermaid_

So lets set that!

![Front Matter flag for mermaid](https://chris-ayers.com/assets/2022/12/mermaid-frontmatter.png)
_Front Matter flag for mermaid_

At this point, everthing should work and embedded mermaid in my markdown posts renders properly!

```
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

```

I’ve done a few other minor customizations so far. Like adding some custom css and some javascript for app insights. Both of those involved a similar process of adding head/custom.html and assets/css/custom.css.

Thanks for following along on this journey. I hope this helps those starting their Jekyll journey or hosting on GitHub Pages.