Yap Chuan Fu
Research Associate at The University of Manchester. I enjoy solving problems using computers and mathematics.
Adding Table of Contents Sidebar to Github Pages (Posts)
Second dive in web design - 7 min read
Published Dec 28, 2022
Lesson from Web Building so far…
I am not web designer, I am awful at it, but I am learning, happily at that. Recently I wrote a very lengthy post, and wanted to add a sidebar containing the table of contents to make it easier to navigate. In my attempt to do this, I learned that it was not very straightforward, I googled “adding side bar to github pages”, and read majority of the posts, the consensus was that using generic GitHub Pages does not really allow for it and we should use a different theme (template) that comes ready made with navigation sidebar, or customise the basic theme oursevles as per this post.
And like many other newbies of web building, I used the bare minimum theme made by GitHub pages by following its instructions. And I have grown attached to its minimalism, so I wanted to just customise what I already had. Unfortunately, the post linked above did not say how, other than that rtfm on web design. I did not have to learn web building and rebuild my website, so I did what I have always done, which is to steal borrow code from the internet. And GitHub made it really easy for code borrowing as source code is all there, further to this we can always right click and inspect element to understand part of a webpage better, so that is how I have learned most of what I needed to add a sidebar. But majority is borrowed from Minimal Mistakes Jekyll theme.
Two main building blocks of web designs
The primary lesson I have learned so far (aside from borrowing code) when it comes to building websites is there’s two main components, HTML and CSS. You need HTML to define a lot of the skeleton of the website, and it involves a lot of < >. Beyond that, CSS styling can help customise the website beyond HTML, more on all these below.
Making sure CSS works
We can customise plenty of things using CSS, and its all stored within a .css file, which we just have to include (import) at the start of every website otherwise the css magic would not appear. This can conveniently be done with a header.html that we can ‘import’ using jekyll liquid {% include header.html %} at the start of every page template. Within header.html, we can import the css styling as such:
<head>
... <!-- everything else goes here-->
<link href="{{ "/assets/styles.css" | relative_url }}" rel="stylesheet" type="text/css">
</head>
Be sure to replace the “/assets/styles.css” location and file name as needed, I have learned some people use “main.css” by default.
Adding Table of Contents Sidebar to Github Pages (Posts)
including sidebar object
So first thing we need to do, is to start from a html template page that already have a sidebar, and GitHub Pages comes with two layout, “stacked” and “sidebar”. Initially, I made every page of mine to have “stacked” layout, but now posts templates would be making use of the “sidebar” template. If we look into the source code, we can see from line 50 onwards thats where it creates the sidebar, with several different div tags. And the place I wanted to insert the table of contents sidebar was in the same div class as where it would add masthead.html in line 52. I kept the masthead.html and just appended the follwing code below it.
{% if page.sidebar.nav %}
{% include nav_list nav=page.sidebar.nav %}
{% else %}
The {% %} tags are the Jekyll Liquid language, I have included the if statement because not every post need a table of contents. But the important line is {% include nav_list nav=page.sidebar.nav %}, which is adding the table of contents navigation side bar, that lets us jump between section easily.
nav_list file
If you are not already familiar with Jekyll liquid, when we call include $object line, we are “importing” another template we have placed within _includes folder. So we need to create a nav_list (no suffix) file within that folder, depending on how you want to style it, you use what my version or the original I borrowed from, which is much more tech-ed out.
navigation yaml
After that nav_list, we still need to make the navigation directory that contains all the title and hyperlinks. This would be the navigation.yml which would have to be stored in _data folder. The full example found here. Important to note, this yaml file stores all the navgation links, and they are all separated with a title which each page can call. In the example linked, the first one is called foo, followed by main and links. Following the title, it would be title of each section (and maybe children section) and its url. For table of contents like mine, we can use relative url, that is we just take section of the url after the base url, e.g. my website’s base url is https://chuanfuyap.github.io, everything after io would be the relative url, e.g. relative url for this post would be /2022/12/28/webdesign2. And if you are using markdown’s hyperlink, you can add #SECTION to the relative url.
To pick which section to call, we need to include them in the page front matter e.g. for this blogpost (the title is whatever you want it):
---
sidebar:
title: "Navigation Links"
nav: web-toc
---
Sticky Sidebar
Aftet you have made the sidebar, another issue to address to have it fixed no matter how far down we scroll, otherwise that would be a pointless navigation bar. To do this, we first wrap the include line with div tag with sticky class as such:
<div class="sidebar sticky">
{% include nav_list nav=page.sidebar.nav %}
</div>
Following this, we need to make use of CSS, go into your website’s CSS file and add the following:
.sidebar {
position: -webkit-sticky;
position: sticky;
top: 0;
}
With that, you now have a static/sticky navigation sidebar that does not disappear no matter how far down you scroll.
Customising/Styling the Sidebar
After all the steps above, you have a sidebar, but it looks rather plain… To make it look better, we fall back to CSS again (remember I said two main components of web building?). There’s few things here to style, which are: “.nav__title”, “.nav__sub-title”, “.nav__list” and “.nav__items”. Frankly, I have no idea how any of it works, so let’s go back to the source and borrow everything and edit them until it works.
To summarise, modify post template, to include
nav_list, make thenav_listfile, then makenavigation.ymlfile. With that you should have a sidebar with table of contents, add div sticky class and edit CSS to make it sticky. Then customise the CSS further to make the buttons look the way you want it.
BONUS: Centering things (anything and everything?)
HTML tags allows us to do many things, including centering, but we need to be mindful that text and other objects are different. For example for most things, we can add ‘center’ to the class within a tag, but for texts, we need to make use of ‘text-center’.
Sometimes HTML centering does not work (I don’t know why it fails), we can instead center with CSS by adding the following to the CSS file.
.center {
display: block;
margin-left: auto;
margin-right: auto;
}
BONUS: displaying CSS and HTML code blocks in markdown posts
Another thing I learned while writing up this post is that when we use markdown to generate CSS and HTML code snippet, it would not render normally, because, the HTML lines would be rendered into the HTML page that is published online. To make sure the code blocks still show the CSS/HTML code, we have make use of Jekyll Liquid to let it know not to process that part of the markdown file into HTML. And we do this by wrapping the code blocks with { raw } { endraw }. Okay be sure to add % to after and before the {} tags to make sure it works, because when I add them into this post it would disappear. Reminder on Liquid language, read the part on Tags to understand what I mean.
The end
Well, that was most of what I have learned when updating my website, hope this helped someone, and thank you Michael Rose for making all these templates and sharing them for free, allowing me to learn from your source code.