feat: single page (#1035)

* feat: spec state badges (#1036)
* chore: update deps
* fix: remove link shortcode
* fix: remove old shortcodes
* chore: rationalise js init- ensure all the js that is needed is bundled and initalised in an orderly manner. previously, shortcodes would include script elements to a remote cdn which can lead to many copies of the same lib being requested in single page mode.
* fix: numbering per heading element. css counters are scoped to the element that first declares them. This change declares the counters at the content root, so that heading elements share them regardless of nesting.
* fix: host katex locally
* fix: dashboard links for single page. re-use the portable link template :woo hoo:
* fix: multiple layout improvements
* feat: bring back old ToC behaviour - This is a loving homage to the original ToC. It brings back all the old behaviours and great perf. TocBot perf is terrible on a large doc, so it is removed, in favour of the old ways. Fixes up resource loading, notably defering katex till well after the page is loaded, to speed up ToC build and reduce the time to get to a useable document.
* chore: bring back appendix. fix glossary headings
* remove header element that wraps headings to avoid issue with org-mode docs not getting headers re-written
* fix missing section headers in content that ment the listings and appendix were missing
* fix nesting of glossary headings
* chore: fix header on small screens
* match the old spec for generating heading ids and linking to them
* fix issues with old content missing h1 elements.
* document what is going on in render-heading and render-link so others may suffer less.


License: MIT
Signed-off-by: Oli Evans <oli@tableflip.io>

Author: hugomrdias

README.md

@@ -175,8 +175,7 @@ Random plain text context ...
 ```
 
 
-## References
-### Markdown links **(Recommended)**
+## References - Markdown links
 These links use "portable links" just like `relref` so you can just give it the name of the file and it will fetch the correct relative link and title for the `<a href="/relative/path" title="page title">` automatically.
 You can override the `<a>` title by passing a second `string` in the link definition.
 
@@ -193,19 +192,6 @@ You can override the `<a>` title by passing a second `string` in the link defini
 
 ```
 
-### Hugo Cross Refs
-Check Hugo's documentation [here](https://gohugo.io/content-management/shortcodes/#ref-and-relref)
-```md
-[Random]({{<relref "randomness">}})
-[Pledge Collateral]({{<relref "storage_power_actor#pledge-collateral">}})
-```
-### Link shortcode
-Theres also `link` shortcode which will fetch the title of the page automatically and use it for the `<a>` text and title, but **DOES NOT** work with anchors (`#anchor-id`)
-```md
-{{<link storage_power_consensus>}}
-# <a href="/systems/filecoin_blockchain/storage_power_consensus" title="Storage Power Consensus">Storage Power Consensus</a>
-```
-
 ## Math mode
 For short snippets of math text you can just use the `{{<katex>}}` shortcode, but if you need to write lots of math in a page you can just use `math-mode` and avoid writting the katex shortcode everywhere.
 

assets/_custom.scss

@@ -2,12 +2,42 @@
 
 // Addons
 
-// @import "plugins/numbered";
+@import "plugins/numbered";
 @import "plugins/scrollbars";
 @import "plugins/toggles";
 @import "table-sort";
 @import "colors";
 @import "dashboard";
+@import "plugins/toc";
+@import "katex";
+
+.markdown {
+    overflow-x: hidden;
+    h1, h2, h3, h4, h5, h6 {
+        padding-top: 1.5rem;
+        margin-bottom: 1rem;
+        a {
+            color: inherit;
+            text-decoration: none;
+            &:visited {
+                color:inherit;
+            }
+            &:hover {
+                text-decoration: none;
+                &::after {
+                    font-size: 70%;
+                    padding-left:0.3em;
+                    color: $color-link;
+                    content: " #"
+                }
+            }
+        }
+    }
+}
+.section-badges {
+    float: right;
+    margin-top:-2.5rem;
+}
 
 // SVG Diagrams
 .diagrams-container {
@@ -98,12 +128,43 @@
 }
 
 // Tweaks
+html {
+    scroll-behavior: auto;
+    touch-action: auto;
+}
+.container {
+    max-width: 89rem;
+}
+.book-menu {
+    flex: 0 0 20rem;
+}
+.book-page {
+    padding-top: 0rem;
+    padding-left: 2rem;
+    max-width: 52rem;
+}
+
 summary {
     outline: none;
 }
 blockquote {
     overflow: auto;
 }
+.book-menu nav {
+    width: 20rem;
+    padding: 1rem 0.2rem 4rem 1rem;
+    position: fixed;
+    top: 0;
+    bottom: 0;
+    overflow-x: initial;
+    overflow-y: hidden;
+}
+
+.book-menu nav .toc {
+    overflow-x: hidden;
+    overflow-y: auto;
+    height: 100%;
+}
 
 .markdown>h1:first-of-type {
     margin-top: 0;
@@ -138,27 +199,33 @@ blockquote {
     padding: 0;
     height: 90vh;
 }
-.book-menu > nav::-webkit-scrollbar,
+.book-menu > nav .toc::-webkit-scrollbar,
 .book-toc > div nav::-webkit-scrollbar{
     width: 8px;
 }
 
-.book-menu > nav::-webkit-scrollbar-thumb,
+.book-menu > nav .toc::-webkit-scrollbar-thumb,
 .book-toc > div nav::-webkit-scrollbar-thumb{
     background: transparent;
 }
 
-.book-menu > nav:hover::-webkit-scrollbar-thumb,
-.book-toc > div nav:hover::-webkit-scrollbar-thumb{
+.book-menu > nav:hover .toc::-webkit-scrollbar-thumb,
+.book-toc > div nav:hover .toc::-webkit-scrollbar-thumb{
     background: rgba(255,255,255,.1);
 }
 
 @media screen and (max-width: 56rem) {
-    .toc {
-        text-align: right;
+    .book-page {
+        padding-left:1rem;
+    }
+    .book-menu {
+        visibility: hidden;
+        margin-inline-start: -20rem;
+    }
+    #menu-control:checked~main .book-menu nav {
+        transform: translateX(20rem);
     }
     .toc-label {
-        margin: 0 0 2rem;
         font-weight:700;
         font-size:10px;
         .gg-menu-motion {
@@ -167,6 +234,15 @@ blockquote {
     }
     .book-header {
         margin-bottom: 2rem;
+        position: fixed;
+        width: 100%;
+        background: white;
+        z-index: 1;
+        padding: 5px 0.6rem;
+        box-shadow: 1px 0 2px 0px rgba(0,0,0,0.2);
+    }
+    #toc-depth-slider {
+        display:none;
     }
 }
 
@@ -182,19 +258,21 @@ blockquote {
     .toc {
         top:78px;
     }
-    .toc-label, .dark-mode-toggle-label {
-        font-size: 10px;
-        font-weight: 700;
-        display: block;
-    }
-    .gg-menu-motion, .gg-dark-mode {
-        display: inline-block;
-        margin-left: 0;
-        margin-right: 0;
-        vertical-align: middle;
-        font-size: 10px;
-        transform: scale(0.7);
-    }
+}
+
+.toc-label, .dark-mode-toggle-label {
+    font-size: 10px;
+    font-weight: 700;
+    display: block;
+    color:$gray-600;
+}
+.gg-menu-motion, .gg-dark-mode {
+    display: inline-block;
+    margin-left: 0;
+    margin-right: 0;
+    vertical-align: middle;
+    font-size: 10px;
+    transform: scale(0.7);
 }
 
 // Colors
@@ -411,7 +489,7 @@ i[class^="gg-"] {
     box-shadow: 4px -6px 0,8px -12px 0;
     border-radius: 4px;
     background: currentColor
-} 
+}
 
 .gg-dark-mode {
     box-sizing: border-box;
@@ -453,3 +531,24 @@ i[class^="gg-"] {
     right:4px;
     top:4px
 }
+
+.state-badge {
+    font-size: 10px;
+    font-weight: 500;   
+}
+.state-badge-link {
+    text-decoration: none !important;
+    color: white !important;
+    &:hover {
+        text-decoration: none;
+    }
+}
+.state-badge-key, .state-badge-value {
+    padding: 2px 5px;
+}
+.state-badge-key {
+    background-color: #555;
+}
+.section-intro .state-badge {
+    display: none;
+}

assets/_katex.scss

@@ -1,3 +1,6 @@
 /* You can override SASS variables here. */
 
 $book-search-results-bg: #f8f9fa !default;
+
+$blue: rgb(14,120,254);
+$color-link: $blue;

assets/_variables.scss

@@ -0,0 +1,21 @@
+import renderMathInElement from 'katex/dist/contrib/auto-render.mjs'
+
+function initKatex () {
+  console.log('init katex')
+  document.querySelectorAll('.math-mode').forEach(function (el) {
+    renderMathInElement(el, {
+      ignoredTags: ["script", "noscript", "style", "textarea"],
+      throwOnError: false,
+      delimiters: [
+          {left: "$$", right: "$$", display: true},
+          {left: "$", right: "$", display: false},
+          {left: "\\(", right: "\\)", display: false},
+          {left: "\\[", right: "\\]", display: true}
+          ]
+    })
+  })
+}
+
+window.addEventListener('load', () => {
+  setTimeout(initKatex, 2000)
+});

assets/katex.js

@@ -0,0 +1,68 @@
+import '@pwabuilder/pwaupdate'
+import { initToc } from './toc.js'
+import panzoom from 'panzoom'
+import tablesort from 'tablesort'
+import Gumshoe from 'gumshoejs'
+
+// Note: the tablesort lib is not ESM friendly, and the sorts expect `Tablesort` to be available on the global
+window.Tablesort = tablesort
+require('tablesort/dist/sorts/tablesort.number.min.js')
+
+function initPanZoom () {
+  console.log('init panzoom')
+  var elements = document.querySelectorAll(".zoomable")
+  elements.forEach(function (el) {
+    panzoom(el.querySelector('*:first-child'), {
+      maxZoom: 10,
+      minZoom: 0.5
+    })
+  })
+}
+
+function initTableSort () {
+  console.log('init tablesort')
+  var elements = document.querySelectorAll(".tablesort")
+  elements.forEach(function (el) {
+    tablesort(el);
+  })
+}
+
+function initTocDepthSlider () {
+  var slider = document.getElementById('toc-depth-slider')
+  var toc = document.querySelector('.toc')
+  
+  slider.addEventListener('change', (event) => {
+    handleSliderChange(Number(event.target.value))
+  })
+
+  function handleSliderChange (depth) {
+    console.log('handleSliderChange', depth)
+    for (let i = 0; i < 6; i++) {
+      toc.querySelectorAll(`.depth-${i}`).forEach(el => {
+        if (i < depth) {
+          el.classList.remove('maybe-hide')
+        } else {
+          el.classList.add('maybe-hide')
+        }
+      })
+    }
+  }
+  // init to the current value
+  handleSliderChange(slider.value)
+}
+
+function initTocScrollSpy () {
+  console.log('initTocScrollSpy')
+  var spy = new Gumshoe('.toc a', {
+    nested: true,
+    nestedClass: 'active-parent'
+  })
+}
+
+window.addEventListener('DOMContentLoaded', () => {
+  initToc({tocSelector:'.toc', contentSelector: '.markdown'})
+  initTocDepthSlider()
+  initTocScrollSpy()
+  initPanZoom()
+  initTableSort()
+});