Toc sidebar (#1366)

Implemented #966.


![image](https://user-images.githubusercontent.com/31376482/234411523-b02087d9-a437-4f77-9f54-de5eef122439.png)

---------

Signed-off-by: George Araujo <george.gcac@gmail.com>

_includes/head.html

@@ -13,6 +13,11 @@
     <!-- Code Syntax Highlighting -->
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/jwarby/jekyll-pygments-themes@master/{{ site.highlight_theme_light | append: '.css' }}" media="" id="highlight_theme_light" />
 
+    {% if page.toc and page.toc.sidebar %}
+    <!-- Sidebar Table of Contents -->
+    <link href="https://cdn.rawgit.com/afeld/bootstrap-toc/v1.0.1/dist/bootstrap-toc.min.css" rel="stylesheet" />
+    {% endif %}
+
     <!-- Styles -->
     {% if site.icon.size <= 4 %}
     <link rel="shortcut icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>{{ site.icon }}</text></svg>">

_includes/scripts/misc.html

@@ -10,6 +10,11 @@
   <script defer src="{{ '/assets/js/zoom.js' | relative_url }}"></script>
 {%- endif -%}
 
+{% if page.toc and page.toc.sidebar %}
+  <!-- Sidebar Table of Contents -->
+  <script defer src="https://cdn.rawgit.com/afeld/bootstrap-toc/v1.0.1/dist/bootstrap-toc.min.js"></script>
+{% endif %}
+
   <!-- Load Common JS -->
   <script defer src="{{ '/assets/js/common.js' | relative_url }}"></script>
   <script defer src="{{ '/assets/js/copy_code.js' | relative_url }}" type="text/javascript"></script>

_layouts/default.html

@@ -17,8 +17,34 @@
 
     <!-- Content -->
     <div class="container mt-5">
+      {% if page.toc and page.toc.sidebar %}
+        {% if page.toc.sidebar == "right" %}
+        <div class="row">
+          <!-- main content area -->
+          <div class="col-sm-9">
             {{ content }}
           </div>
+          <!-- sidebar, which will move to the top on a small screen -->
+          <div class="col-sm-3">
+            <nav id="toc-sidebar" class="sticky-top"></nav>
+          </div>
+        </div>
+        {% else %}
+        <div class="row">
+          <!-- sidebar, which will move to the top on a small screen -->
+          <div class="col-sm-3">
+            <nav id="toc-sidebar" class="sticky-top"></nav>
+          </div>
+          <!-- main content area -->
+          <div class="col-sm-9">
+            {{ content }}
+          </div>
+        </div>
+        {% endif %}
+      {% else %}
+        {{ content }}
+      {% endif %}
+    </div>
 
     <!-- Footer -->
     {%- include footer.html %}

_layouts/post.html

@@ -40,7 +40,7 @@ layout: default
   </header>
 
   <article class="post-content">
-    {% if page.toc %}
+    {% if page.toc and page.toc.beginning %}
     <div id="table-of-contents">
       {% toc %}
     </div>

_posts/2023-03-20-table-of-contents.md

@@ -6,13 +6,19 @@ description: an example of a blog post with table of contents
 categories: sample-posts toc
 giscus_comments: true
 related_posts: false
-toc: true
+toc:
+  beginning: true
 ---
-This post shows how to add a table of contents.
+This post shows how to add a table of contents in the beginning of the post.
 
 ## Adding a Table of Contents
 
-To add a table of contents to a post, simply add `toc: true` to the front matter of the post. The table of contents will be automatically generated from the headings in the post.
+To add a table of contents to a post, simply add
+```yml
+toc:
+  beginning: true
+```
+to the front matter of the post. The table of contents will be automatically generated from the headings in the post.
 
 ### Example of Sub-Heading 1
 

_posts/2023-04-25-sidebar-table-of-contents.md

@@ -0,0 +1,42 @@
+---
+layout: post
+title: a post with table of contents on a sidebar
+date: 2023-04-25 10:14:00-0400
+description: an example of a blog post with table of contents on a sidebar
+categories: sample-posts toc sidebar
+giscus_comments: true
+related_posts: false
+toc:
+  sidebar: left
+---
+This post shows how to add a table of contents as a sidebar.
+
+## Adding a Table of Contents
+
+To add a table of contents to a post as a sidebar, simply add
+```yml
+toc:
+  sidebar: left
+```
+to the front matter of the post. The table of contents will be automatically generated from the headings in the post. If you wish to display the sidebar to the right, simply change `left` to `right`.
+
+### Example of Sub-Heading 1
+
+Jean shorts raw denim Vice normcore, art party High Life PBR skateboard stumptown vinyl kitsch. Four loko meh 8-bit, tousled banh mi tilde forage Schlitz dreamcatcher twee 3 wolf moon. Chambray asymmetrical paleo salvia, sartorial umami four loko master cleanse drinking vinegar brunch. <a href="https://www.pinterest.com">Pinterest</a> DIY authentic Schlitz, hoodie Intelligentsia butcher trust fund brunch shabby chic Kickstarter forage flexitarian. Direct trade <a href="https://en.wikipedia.org/wiki/Cold-pressed_juice">cold-pressed</a> meggings stumptown plaid, pop-up taxidermy. Hoodie XOXO fingerstache scenester Echo Park. Plaid ugh Wes Anderson, freegan pug selvage fanny pack leggings pickled food truck DIY irony Banksy.
+
+### Example of another Sub-Heading 1
+
+Jean shorts raw denim Vice normcore, art party High Life PBR skateboard stumptown vinyl kitsch. Four loko meh 8-bit, tousled banh mi tilde forage Schlitz dreamcatcher twee 3 wolf moon. Chambray asymmetrical paleo salvia, sartorial umami four loko master cleanse drinking vinegar brunch. <a href="https://www.pinterest.com">Pinterest</a> DIY authentic Schlitz, hoodie Intelligentsia butcher trust fund brunch shabby chic Kickstarter forage flexitarian. Direct trade <a href="https://en.wikipedia.org/wiki/Cold-pressed_juice">cold-pressed</a> meggings stumptown plaid, pop-up taxidermy. Hoodie XOXO fingerstache scenester Echo Park. Plaid ugh Wes Anderson, freegan pug selvage fanny pack leggings pickled food truck DIY irony Banksy.
+
+## Customizing Your Table of Contents
+{:data-toc-text="Customizing"}
+
+If you want to learn more about how to customize the table of contents of your sidebar, you can check the [bootstrap-toc](https://afeld.github.io/bootstrap-toc/) documentation. Notice that you can even customize the text of the heading that will be displayed on the sidebar.
+
+### Example of Sub-Heading 2
+
+Jean shorts raw denim Vice normcore, art party High Life PBR skateboard stumptown vinyl kitsch. Four loko meh 8-bit, tousled banh mi tilde forage Schlitz dreamcatcher twee 3 wolf moon. Chambray asymmetrical paleo salvia, sartorial umami four loko master cleanse drinking vinegar brunch. <a href="https://www.pinterest.com">Pinterest</a> DIY authentic Schlitz, hoodie Intelligentsia butcher trust fund brunch shabby chic Kickstarter forage flexitarian. Direct trade <a href="https://en.wikipedia.org/wiki/Cold-pressed_juice">cold-pressed</a> meggings stumptown plaid, pop-up taxidermy. Hoodie XOXO fingerstache scenester Echo Park. Plaid ugh Wes Anderson, freegan pug selvage fanny pack leggings pickled food truck DIY irony Banksy.
+
+### Example of another Sub-Heading 2
+
+Jean shorts raw denim Vice normcore, art party High Life PBR skateboard stumptown vinyl kitsch. Four loko meh 8-bit, tousled banh mi tilde forage Schlitz dreamcatcher twee 3 wolf moon. Chambray asymmetrical paleo salvia, sartorial umami four loko master cleanse drinking vinegar brunch. <a href="https://www.pinterest.com">Pinterest</a> DIY authentic Schlitz, hoodie Intelligentsia butcher trust fund brunch shabby chic Kickstarter forage flexitarian. Direct trade <a href="https://en.wikipedia.org/wiki/Cold-pressed_juice">cold-pressed</a> meggings stumptown plaid, pop-up taxidermy. Hoodie XOXO fingerstache scenester Echo Park. Plaid ugh Wes Anderson, freegan pug selvage fanny pack leggings pickled food truck DIY irony Banksy.

_sass/_base.scss

@@ -860,3 +860,17 @@ progress::-moz-progress-bar {
     opacity: 1;
   }
 }
+
+nav[data-toggle="toc"] {
+  top: 5rem;
+}
+
+/* small screens */
+@media (max-width: 576px) {
+  /* override stickyness so that the navigation does not follow scrolling */
+  nav[data-toggle="toc"] {
+    visibility: hidden;
+    height: 0;
+    top: 0;
+  }
+}

assets/js/common.js

@@ -9,3 +9,15 @@ $(document).ready(function() {
     });
     $('a').removeClass('waves-effect waves-light');
 });
+
+// bootstrap-toc
+$(function () {
+    if($('#toc-sidebar').length){
+        var navSelector = "#toc-sidebar";
+        var $myNav = $(navSelector);
+        Toc.init($myNav);
+        $("body").scrollspy({
+            target: navSelector,
+        });
+    }
+});