This repository hosts code for a plugin for Jekyll based sites that adds a sidebar to your regular blog post. The plugin is simple to use. This plugin allows for multiple sidebars within a single blog post page. This has been tested with Jekyll's minima theme.
The sidebar feature allows for better organization and more beautiful presentation of information. By default, presenting long form content with the minima theme can appear boring to the user. The boring nature limits user retention and interest. The author is not just interested in presenting content, but to have the reader enjoy it and consume it fully.
By adding a sidebar, the user will know where they are in the long text and where they are going - this allows for a parallel form of information - like a compass on a map. In the age of short attention spans this compass is not only a navigation tool, but also a nice visual fidget toy for the viewer.
In addition, the sidebar can be used multiple times within a single blog post and is distinct from regular text as the sidebar reduces the content's width. The alternating width adds 'hills' to the content which makes the readers's walk through your page a pleasant hike.
Finally, the elements selected by the author to be as headers in the sidebar allow the authors to emphasize the points the reader nees to care about. The reader may forget all the words in your write up, but they will remember the points.
Copy the plugin folder jekyll-side-bar from this repositories lib into your Jekyll based site's _plugins folder.
Your markdown blog posts will have have a header section like the following
---
layout: post
title: "Welcome to Jekyll!"
date: 2022-11-11 16:27:06 -0600
categories: jekyll update
---
Due to the layout being post, make sure your modify your post.html in your layout directory to filter the content via | toc operation since this plugin is a filter. Here is a before / after for a sample layout page (yours may be different).
| Before | After |
---
layout: default
---
<div class="post">
<article class="post-content">
{{ content }}
</article>
</div> |
---
layout: default
---
<div class="post">
<article class="post-content">
{{ content | toc }}
</article>
</div> |
Wrap your content that you want to be part of the sidebar with <!--toc_start--> and <!--toc_end-->. All lines that are wrapped that are h2 headings (e.g. ## Another day, another heading) will be made into a link in the sidebar. <!--toc_start--> must be followed by a h2 heading line. The following section below will be modified into the following image.
<!--toc_start-->
## Just another heading
...
## A heading
...
{% highlight ruby %}
def print_hi(name)
puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.
{% endhighlight %}
<!--toc_end-->
To get a live demonstration then go to the test_site directory and run jekyll serve in the terminal. Otherwise, check out the gifs below:
| Features | Demonstration |
|---|---|
| A sidebar can be added in between regular content. The sidebar minizes the content width, but adds a compass for navigation. You can have multiple sidebars throughout your blog post. The sidebar content can contain code/image/text. | |
| You can use the sidebar to jump around. The highlighted/active link in the sidebar shows where you are currently located at. |  |
You can also have long sidebars. The sidebar gets its own scrollbar which auto adjusts when the page's scrollbar is scrolled to an h2 heading that is not visible in the sidebar |
 |
| In mobile view, there is a button on the side of the screen. When pressed it shows you the sidebar with your current section highlighted. The text that is organized with the sidebar has a grey background to differentiate to non sidebar content. |  |
| In mobile view, the sidebar dissapears upon scrolling or pressing something outside the sidebar (or if pressing the sidebar's "x" button.) It can be used for navigating to links you are interested in. |  |
| In mobile view, long sidebars auto adjust when your current scroll position on the page is viewing a header outside |  |