Add table of contents to the integrations pages (#13572)

Co-authored-by: Franck Nijhof <git@frenck.dev>

Gemfile

@@ -15,6 +15,7 @@ group :jekyll_plugins do
   gem 'jekyll-sitemap', '1.4.0'
   gem 'jekyll-time-to-read', '0.1.2'
   gem 'jekyll-commonmark', '1.3.1'
+  gem 'jekyll-toc', '0.14.0'
 end
 
 gem 'sinatra', '2.1.0'

Gemfile.lock

@@ -56,6 +56,9 @@ GEM
       jekyll (>= 3.7, < 5.0)
     jekyll-time-to-read (0.1.2)
       jekyll
+    jekyll-toc (0.14.0)
+      jekyll (>= 3.8)
+      nokogiri (~> 1.10)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     kramdown (2.3.0)
@@ -124,6 +127,7 @@ DEPENDENCIES
   jekyll-paginate (= 1.1.0)
   jekyll-sitemap (= 1.4.0)
   jekyll-time-to-read (= 0.1.2)
+  jekyll-toc (= 0.14.0)
   nokogiri (= 1.10.10)
   rake (= 13.0.1)
   sass-globbing (= 1.1.5)

_config.yml

@@ -46,6 +46,7 @@ highlighter: none
 
 plugins:
   - jekyll-time-to-read
+  - jekyll-toc
 
 paginate: 10 # Posts per page on the blog index
 paginate_path: "blog/posts/:num" # Directory base for pagination URLs eg. /posts/2/
@@ -123,6 +124,7 @@ defaults:
       featured: false
   # Defaults for blogs posts
   - scope:
+      path: ""
       type: posts
     values:
       layout: post
@@ -130,9 +132,26 @@ defaults:
       footer: true
       sharing: true
       sidebar: true
+  # Enable table of contents for integrations
+  #
+  # To set toc as a default value, we need to set the scope with an empty path
+  # and the collection as type
+  # https://github.com/toshimaru/jekyll-toc/issues/116#issuecomment-644205770
+  #
+  - scope:
+      path: ""
+      type: integrations
+    values:
+      toc: true
 
 # Support for files Jekyll will normally exclude
 include:
   - "_headers"
   - "_redirects"
   - ".well-known"
+
+# Table of contents
+# https://github.com/toshimaru/jekyll-toc
+toc:
+  min_level: 2 # default: 1
+  max_level: 3 # default: 6

sass/custom/_paulus.scss

@@ -426,6 +426,21 @@ div.note {
 .aside-module {
   .section {
     margin-bottom: 10px;
+
+    ul.section-nav {
+      margin-left: 0px;
+
+      li.toc-entry {
+        list-style-type: none;
+        li {
+          list-style-type: circle;
+          margin-left: 1em;
+        }
+        ul {
+          margin-left: 1em;
+        }
+      }
+    }
   }
 
   .brand-logo-container {

source/_includes/asides/component_navigation.html

@@ -66,6 +66,12 @@
     </ul>
     </div>
   {%- endif -%}
+
+  {%- unless page.no_toc -%}
+    <div class='section'>
+    <h1 class="title delta">On this page</h1>
+    {% toc %}
+  {%- endunless -%}
 </section>
 
 <script src="https://alerts.home-assistant.io/ce-alert-link.js"></script>