✨ Add Tables of Contents to articles

CHANGELOG.md

@@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 - Site search powered by Fuse.js
 - Automatic Markdown image resizing and srcset generation
 - Performance and Accessibility improvements to achieve perfect Lighthouse scores
+- Tables of Contents on article pages
 - Taxonomies on article and list pages
 - Author `headline` parameter
 - Skip to content links

assets/css/compiled/main.css

@@ -994,6 +994,40 @@ body a, body button {
   padding-left: 0px;
 }
 
+/* Table of Contents */
+
+.toc ul, .toc li {
+  margin-top: 0.25rem;
+  margin-bottom: 0.25rem;
+  list-style-type: none;
+  padding-left: 0px;
+  padding-right: 0px;
+  line-height: 1.375;
+}
+
+[dir="ltr"] .toc ul ul {
+  padding-left: 1rem;
+}
+
+[dir="rtl"] .toc ul ul {
+  padding-right: 1rem;
+}
+
+.toc a {
+  font-weight: 400;
+  --tw-text-opacity: 1;
+  color: rgba(var(--color-neutral-700), var(--tw-text-opacity));
+}
+
+.dark .toc a {
+  --tw-text-opacity: 1;
+  color: rgba(var(--color-neutral-400), var(--tw-text-opacity));
+}
+
+[dir="rtl"] .toc ul > li {
+  margin-right: 0px;
+}
+
 /* -- Chroma Highlight -- */
 
 /* Background */
@@ -1418,6 +1452,10 @@ body a, body button {
   z-index: 10;
 }
 
+.order-first {
+  order: -9999;
+}
+
 .m-auto {
   margin: auto;
 }
@@ -1636,6 +1674,10 @@ body a, body button {
   max-width: 65ch;
 }
 
+.max-w-full {
+  max-width: 100%;
+}
+
 .max-w-\[10rem\] {
   max-width: 10rem;
 }
@@ -1644,10 +1686,6 @@ body a, body button {
   max-width: 48rem;
 }
 
-.max-w-full {
-  max-width: 100%;
-}
-
 .flex-none {
   flex: none;
 }
@@ -1739,6 +1777,10 @@ body a, body button {
   border-radius: 0.25rem;
 }
 
+.rounded-lg {
+  border-radius: 0.5rem;
+}
+
 .\!rounded-md {
   border-radius: 0.375rem !important;
 }
@@ -1861,6 +1903,11 @@ body a, body button {
   padding-bottom: 2rem;
 }
 
+.px-0 {
+  padding-left: 0px;
+  padding-right: 0px;
+}
+
 .px-2 {
   padding-left: 0.5rem;
   padding-right: 0.5rem;
@@ -2229,6 +2276,10 @@ body a, body button {
   margin-left: 0.25rem;
 }
 
+[dir="ltr"] .ltr\:-ml-5 {
+  margin-left: -1.25rem;
+}
+
 [dir="ltr"] .ltr\:block {
   display: block;
 }
@@ -2241,10 +2292,18 @@ body a, body button {
   display: none;
 }
 
+[dir="ltr"] .ltr\:border-l {
+  border-left-width: 1px;
+}
+
 [dir="ltr"] .ltr\:pr-2 {
   padding-right: 0.5rem;
 }
 
+[dir="ltr"] .ltr\:pl-5 {
+  padding-left: 1.25rem;
+}
+
 [dir="ltr"] .ltr\:pr-3 {
   padding-right: 0.75rem;
 }
@@ -2269,6 +2328,10 @@ body a, body button {
   margin-right: 0.25rem;
 }
 
+[dir="rtl"] .rtl\:-mr-5 {
+  margin-right: -1.25rem;
+}
+
 [dir="rtl"] .rtl\:block {
   display: block;
 }
@@ -2281,10 +2344,18 @@ body a, body button {
   display: none;
 }
 
+[dir="rtl"] .rtl\:border-r {
+  border-right-width: 1px;
+}
+
 [dir="rtl"] .rtl\:pl-2 {
   padding-left: 0.5rem;
 }
 
+[dir="rtl"] .rtl\:pr-5 {
+  padding-right: 1.25rem;
+}
+
 [dir="rtl"] .rtl\:pl-3 {
   padding-left: 0.75rem;
 }
@@ -2413,6 +2484,11 @@ body a, body button {
   color: rgba(var(--color-neutral-800), var(--tw-text-opacity));
 }
 
+.dark .dark\:text-neutral-100 {
+  --tw-text-opacity: 1;
+  color: rgba(var(--color-neutral-100), var(--tw-text-opacity));
+}
+
 .dark .dark\:hover\:border-primary-600:hover {
   --tw-border-opacity: 1;
   border-color: rgba(var(--color-primary-600), var(--tw-border-opacity));
@@ -2530,10 +2606,39 @@ body a, body button {
 }
 
 @media (min-width: 1024px) {
+  .lg\:sticky {
+    position: -webkit-sticky;
+    position: sticky;
+  }
+
+  .lg\:top-10 {
+    top: 2.5rem;
+  }
+
+  .lg\:order-last {
+    order: 9999;
+  }
+
+  .lg\:mt-3 {
+    margin-top: 0.75rem;
+  }
+
+  .lg\:hidden {
+    display: none;
+  }
+
   .lg\:w-1\/4 {
     width: 25%;
   }
 
+  .lg\:max-w-xs {
+    max-width: 20rem;
+  }
+
+  .lg\:flex-row {
+    flex-direction: row;
+  }
+
   .lg\:p-\[12vh\] {
     padding: 12vh;
   }
@@ -2542,6 +2647,14 @@ body a, body button {
     padding-left: 8rem;
     padding-right: 8rem;
   }
+
+  [dir="ltr"] .ltr\:lg\:pl-8 {
+    padding-left: 2rem;
+  }
+
+  [dir="rtl"] .rtl\:lg\:pr-8 {
+    padding-right: 2rem;
+  }
 }
 
 @media (min-width: 1280px) {

assets/css/main.css

@@ -62,6 +62,21 @@ body button {
   @apply rtl:pl-0;
 }
 
+/* Table of Contents */
+.toc ul,
+.toc li {
+  @apply px-0 my-1 leading-snug list-none;
+}
+.toc ul ul {
+  @apply ltr:pl-4 rtl:pr-4;
+}
+.toc a {
+  @apply font-normal text-neutral-700 dark:text-neutral-400;
+}
+.toc ul > li {
+  @apply rtl:mr-0;
+}
+
 /* -- Chroma Highlight -- */
 /* Background */
 .markdown .chroma {

config/_default/markup.toml

@@ -7,3 +7,7 @@
 
 [highlight]
   noClasses = false
+
+[tableOfContents]
+  startLevel = 2
+  endLevel = 4

config/_default/params.toml

@@ -30,6 +30,7 @@ enableSearch = false
   showPagination = true
   showReadingTime = true
   showTaxonomies = false
+  showTableOfContents = false
   showWordCount = false
   # sharingLinks = ["facebook", "twitter", "pinterest", "reddit", "linkedin", "email"]
 

exampleSite/config/_default/markup.toml

@@ -7,3 +7,7 @@
 
 [highlight]
   noClasses = false
+
+[tableOfContents]
+  startLevel = 2
+  endLevel = 4

exampleSite/config/_default/params.toml

@@ -30,6 +30,7 @@ mainSections = ["samples"]
   showPagination = true
   showReadingTime = true
   showTaxonomies = false
+  showTableOfContents = true
   showWordCount = false
   # sharingLinks = ["facebook", "twitter", "pinterest", "reddit", "linkedin", "email"]
 

i18n/de.yaml

@@ -6,6 +6,7 @@ article:
     one: "{{ .Count }} min"
     other: "{{ .Count }} min"
   reading_time_title: "Lesezeit"
+  # table_of_contents: "Table of Contents"
   # word_count:
   # one: "{{ .Count }} word"
   # other: "{{ .Count }} words"

i18n/en.yaml

@@ -6,6 +6,7 @@ article:
     one: "{{ .Count }} min"
     other: "{{ .Count }} mins"
   reading_time_title: "Reading time"
+  table_of_contents: "Table of Contents"
   word_count:
     one: "{{ .Count }} word"
     other: "{{ .Count }} words"

i18n/es.yaml

@@ -6,6 +6,7 @@ article:
     one: "{{ .Count }} min"
     other: "{{ .Count }} mins"
   reading_time_title: "Tiempo de lectura"
+  # table_of_contents: "Table of Contents"
   # word_count:
   # one: "{{ .Count }} word"
   # other: "{{ .Count }} words"

i18n/fr.yaml

@@ -6,6 +6,7 @@ article:
     one: "{{ .Count }} min"
     other: "{{ .Count }} mins"
   reading_time_title: "Temps de lecture"
+  # table_of_contents: "Table of Contents"
   # word_count:
   # one: "{{ .Count }} word"
   # other: "{{ .Count }} words"

i18n/pt-BR.yaml

@@ -6,6 +6,7 @@ article:
     one: "{{ .Count }} minuto"
     other: "{{ .Count }} minutos"
   reading_time_title: "Tempo de leitura"
+  # table_of_contents: "Table of Contents"
   # word_count:
   # one: "{{ .Count }} word"
   # other: "{{ .Count }} words"

i18n/zh.yaml

@@ -5,6 +5,7 @@ article:
   reading_time:
     other: "{{ .Count }} 分钟"
   reading_time_title: "预计阅读"
+  # table_of_contents: "Table of Contents"
   word_count:
     one: "{{ .Count }} 字"
     other: "{{ .Count }} 字"

layouts/_default/single.html

@@ -1,6 +1,6 @@
 {{ define "main" }}
-  <article class="max-w-prose">
-    <header>
+  <article>
+    <header class="max-w-prose">
       {{ if .Site.Params.article.showBreadcrumbs | default false }}
         {{ partial "breadcrumbs.html" . }}
       {{ end }}
@@ -11,10 +11,19 @@
         {{ partial "article-meta.html" (dict "context" . "scope" "single") }}
       </div>
     </header>
-    <section class="markdown dark:markdown-invert">
+    <section class="flex flex-col max-w-full mt-0 lg:flex-row markdown dark:markdown-invert">
+      {{ if and (.Params.showTableOfContents | default (.Site.Params.article.showTableOfContents | default false)) (in .TableOfContents "<ul") }}
+        <div class="order-first px-0 lg:max-w-xs ltr:lg:pl-8 rtl:lg:pr-8 lg:order-last">
+          <div class="ltr:pl-5 rtl:pr-5 toc lg:sticky lg:top-10">
+            {{ partial "toc.html" . }}
+          </div>
+        </div>
+      {{ end }}
+      <div class="max-w-prose">
         {{ .Content | emojify }}
+      </div>
     </section>
-    <footer class="pt-8">
+    <footer class="pt-8 max-w-prose">
       {{ partial "author.html" . }}
       {{ partial "sharing-links.html" . }}
       {{ partial "article-pagination.html" . }}

layouts/partials/toc.html

@@ -0,0 +1,12 @@
+<details open class="mt-0 overflow-hidden rounded-lg rtl:pr-5 ltr:pl-5 ltr:-ml-5 rtl:-mr-5 lg:mt-3">
+  <summary
+    class="block py-1 text-lg font-semibold rtl:pr-5 ltr:pl-5 ltr:-ml-5 rtl:-mr-5 text-neutral-800 dark:text-neutral-100 lg:hidden bg-neutral-100 dark:bg-neutral-700"
+  >
+    {{ i18n "article.table_of_contents" }}
+  </summary>
+  <div
+    class="py-2 border-dotted ltr:border-l rtl:border-r rtl:pr-5 ltr:pl-5 ltr:-ml-5 rtl:-mr-5 border-neutral-300 dark:border-neutral-600"
+  >
+    {{ .TableOfContents }}
+  </div>
+</details>