Tabbed Content in Minimal Mistakes
Tabbed content is pretty useful whenever you’re writing a blog post that highlights code snippets in multiple programming languages or installation commands that depend on what OS you’re running (ie. Mac/Windows/Linux).
Minimal Mistakes (the theme powering this Jekyll site) has some pretty nifty built-in syntax highlighting for highlighting code depending on what language you specify. Unfortunately, it doesn’t come with a way to create tabbed content. But luckily for us, Minimal Mistakes as a theme is highly customizable so why not implement this feature ourselves.
I’ll refer to the concept of having content separated by tabs as “tablists” throughout.
NOTE: Ideally, you’d use an actual tool meant for writing technical documentation to implement a sleeker tab/content system, but what we have is pretty polished IMO.
Features
- Content separated by clickable tabs (duh)
- Code segments with syntax highlighting
- Ability to add additional text content
- Support for multiple tablist groups
- Ability to scroll for overflowed tabs
- Nested tablists (see the “Nested Python” tab)
- Stylistically coherent with MM concepts/themes
Demo
In typical CS fashion, here you have the world’s most famous program written in various different programming languages:
print("Hello World");
Additional area under the code content where one
can add text that is also formatted in markdown.
You can add links or even images!
Usage
Generate a tablist element with content separated by titled tabs.
Each tabbed content element may contain syntactically highlighted
lines of code followed by optional markdown text content.
To place a tablist add the necessary YAML Front Matter.
| Name | Required | Description |
|---|---|---|
| title | Required | Title of the content tab. |
| language | Optional | Specified programming language of the code content for syntax highlighting. See Rouge for a list of supported languages |
| code_content | Optional | Code content. |
| text_content | Optional | Text content (markdown parsable). |
tablist:
- title: Python
language: python
code_content: |
print("Hello World");
text_content: |
Additional area under the code content where one
can add text that is also formatted in **markdown**.
You can add [links](https://qiujames.github.io/) or even images!
- title: Java...
Indentation matters! The YAML Front Matter expects
one level of indentation after the | character
(to indicate multiline front matter content).
The contents positioning and spacing relative
to that indentation will be perserved in the final output.
And then drop-in the tablist include in the body where you’d like it to appear.
| Include Parameter | Required | Description | Default |
|---|---|---|---|
| id | Optional | To add multiple tablists to a document uniquely name them in the YAML Front Matter and reference in {% include tablist id="tablist_id" %}
|
tablist |
{% include tablist %}
<!-- OR -->
{% include tablist id="tablist_id" %}
Tablists were heavily inspired by the
gallery
Jekyll helper.
We also stylistically follow the Minimal Mistakes documentation.
Implementation
Since Jekyll utilizes the template language Liquid (it just allows us to insert stuff into HTML), we can insert an HTML block with the corresponding tab content in.
To do so, we create an includes html block that will get inserted whenever it comes across the {% include tablist %} in the markdown. When it is inserted, it will loop across the written contents in the YAML front content and then correspondingly layout the contents and highlight code as needed. We finally write some javascript to toggle the displayed content and keep an underline on the selected tab.
The trickiest part here was styling the elements to match up coherently with the rest of the Minimal Mistakes theme and getting the markdown to render correctly within Liquid since Markdown and HTML don’t mix well. Feel free to check out the code here.
And there you have it! A custom built functionality supporting tabbed content in Minimal Mistakes.