Add TOC to distill blog posts (alshedivat#470)

jwuphysics · Nov 21, 2021 · a0cfbbd · a0cfbbd
1 parent 7f10dc3
commit a0cfbbd
Show file tree

Hide file tree

Showing 5 changed files with 142 additions and 36 deletions.
diff --git a/_layouts/distill.html b/_layouts/distill.html
@@ -67,6 +67,24 @@ <h1>{{ page.title }}</h1>
       <d-byline></d-byline>
 
       <d-article>
+        {% if page.toc %}
+        <d-contents>
+          <nav class="l-text figcaption">
+          <h3>Contents</h3>
+            {% for section in page.toc %}
+            <div><a href="#{{ section.name | downcase | replace: ' ','-' }}">{{ section.name }}</a></div>
+            {% if section.subsections %}
+            <ul>
+              {% for subsection in section.subsections %}
+              <li><a href="#{{ subsection.name | downcase | replace: ' ','-' }}">{{ subsection.name }}</a></li>
+              {% endfor %}
+            </ul>
+            {% endif %}
+            {% endfor %}
+          </nav>
+        </d-contents>
+        {% endif %}
+
         {{ content }}
       </d-article>
 

diff --git a/_posts/2018-12-22-distill.md b/_posts/2018-12-22-distill.md
@@ -20,6 +20,24 @@ authors:
 
 bibliography: 2018-12-22-distill.bib
 
+# Optionally, you can add a table of contents to your post.
+# NOTES:
+#   - make sure that TOC names match the actual section names
+#     for hyperlinks within the post to work correctly.
+#   - we may want to automate TOC generation in the future using
+#     jekyll-toc plugin (https://github.com/toshimaru/jekyll-toc).
+toc:
+  - name: Equations
+    # if a section has subsections, you can add them as follows:
+    # subsections:
+    #   - name: Example Child Subsection 1
+    #   - name: Example Child Subsection 2
+  - name: Citations
+  - name: Footnotes
+  - name: Code Blocks
+  - name: Layouts
+  - name: Other Typography
+
 # Below is an example of injecting additional post-specific styles.
 # If you use this post as a template, delete this _styles block.
 _styles: >
@@ -153,8 +171,11 @@ It does not interrupt the normal flow of `.l-body` sized text except on mobile s
   <p>.l-gutter</p>
 </div>
 
+***
+
+## Other Typography
 
-Emphasis, aka italics, with *asterisks* or _underscores_.
+Emphasis, aka italics, with *asterisks* (`*asterisks*`) or _underscores_ (`_underscores_`).
 
 Strong emphasis, aka bold, with **asterisks** or __underscores__.
 
@@ -253,20 +274,6 @@ Quote break.
 > This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can *put* **Markdown** into a blockquote. 
 
 
-Three or more...
-
----
-
-Hyphens
-
-***
-
-Asterisks
-
-___
-
-Underscores
-
 Here's a line for us to start with.
 
 This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

diff --git a/_sass/_distill.scss b/_sass/_distill.scss
@@ -3,7 +3,7 @@
  ******************************************************************************/
 
 d-byline {
-  border-top-color: $grey-color-light !important;
+  border-top-color: var(--global-divider-color) !important;
 }
 
 d-byline h3 {
@@ -18,20 +18,79 @@ d-byline a, d-article d-byline a {
 }
 
 d-article {
-  border-top-color: #e8e8e8 !important;
+  border-top-color: var(--global-divider-color) !important;
   a, p, h1, h2, h3, h4, h5, h6, li, table {
     color: var(--global-text-color) !important;
   }
-  a, h1, h2, hr {
-    border-bottom-color: $grey-color-light !important;
+  a, h1, h2, hr, table, table th, table td {
+    border-bottom-color: var(--global-divider-color) !important;
   }
   a:hover {
     border-bottom-color: var(--global-hover-color) !important;
   }
+  b i {
+    display: inline;
+  }
+
+  d-contents {
+    align-self: start;
+    grid-column: 1 / 4;
+    grid-row: auto / span 4;
+    justify-self: end;
+    margin-top: 0em;
+    padding-left: 2em;
+    padding-right: 3em;
+    border-right: 1px solid var(--global-divider-color);
+    width: calc(max(70%, 300px));
+    margin-right: 0px;
+    margin-top:  0em;
+    display: grid;      
+    grid-template-columns: 
+      minmax(8px, 1fr) [toc] auto 
+      minmax(8px, 1fr) [toc-line] 1px
+      minmax(32px, 2fr);
+
+    nav {      
+      grid-column: toc;
+      a {
+        border-bottom: none !important;
+        &:hover {
+          border-bottom: 1px solid var(--global-text-color) !important;
+        }
+      }
+      h3 {
+        margin-top: 0;
+        margin-bottom: 1em;
+      }
+      div {
+        display: block;
+        outline: none;
+        margin-bottom: 0.8em;
+        color: rgba(0, 0, 0, 0.8);
+        font-weight: bold;
+      }
+      ul {
+        padding-left: 1em;
+        margin-top: 0;
+        margin-bottom: 6px;
+        list-style-type: none;
+        li {
+          margin-bottom: 0.25em;
+        }
+      }
+    }
+    .figcaption {
+      line-height: 1.4em;
+    }
+    toc-line {
+      border-right: 1px solid var(--global-divider-color);
+      grid-column: toc-line;
+    }
+  }
 }
 
 d-appendix {
-  border-top-color: $grey-color-light !important;
+  border-top-color: var(--global-divider-color) !important;
   color: var(--global-distill-app-color) !important;
   h3, li, span {
     color: var(--global-distill-app-color) !important;
@@ -43,3 +102,21 @@ d-appendix {
     }
   }
 }
+
+@media (max-width: 1024px) {
+  d-article {
+    d-contents {
+      display: block;
+      grid-column-start: 2;
+      grid-column-end: -2;
+      padding-bottom: 0.5em;
+      margin-bottom: 1em;
+      padding-top: 0.5em;
+      width: 100%;
+      border: 1px solid var(--global-divider-color);
+      nav {
+        grid-column: none;
+      }
+    }
+  }
+}
diff --git a/_sass/_layout.scss b/_sass/_layout.scss
@@ -2,21 +2,25 @@
  * Content
  ******************************************************************************/
 
- body {
-   padding-bottom: 70px;
-   color: var(--global-text-color);
-   background-color: var(--global-bg-color);
- }
-
- body.fixed-top-nav {
-   // Add some padding for the nav-bar.
-   padding-top: 56px;
- }
-
- body.sticky-bottom-footer {
-   // Remove padding below footer.
-   padding-bottom: 0;
- }
+body {
+  padding-bottom: 70px;
+  color: var(--global-text-color);
+  background-color: var(--global-bg-color);
+
+  h1, h2, h3, h4, h5, h6 {
+    scroll-margin-top: 66px;
+  }
+}
+
+body.fixed-top-nav {
+  // Add some padding for the nav-bar.
+  padding-top: 56px;
+}
+
+body.sticky-bottom-footer {
+  // Remove padding below footer.
+  padding-bottom: 0;
+}
 
 .container {
   max-width: $max-content-width;

diff --git a/assets/css/main.scss b/assets/css/main.scss
@@ -4,7 +4,7 @@
 @charset "utf-8";
 
 // Dimensions
-$max-content-width: {{site.max_width}};
+$max-content-width: {{ site.max_width }};
 
 @import
   "variables",