feat: build toc and dashboard in hugo (#1122)

- Avoid building the ToC and the dashboard on the client side by parse data from dom and building the toc from data. Generates a toc.json file in the hugo data dir, which is then used by the toc partial and the dashboard-spec shortcode. 

fixes #1125 

- Refactor watchers. Add watch.js to configure chokidar. Pass watcher to each tool via an exported `configureWatcher` method. Allow tools to be run as scripts or required as modules

see #1133

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

.gitignore

@@ -5,4 +5,5 @@ public/
 yarn.lock
 node_modules
 resources
-static/_gen
+static/_gen
+data/toc.json

assets/js/main.js

@@ -1,9 +1,6 @@
 import '@pwabuilder/pwaupdate'
-import { initToc } from './toc.js'
 import tablesort from 'tablesort'
 import Gumshoe from 'gumshoejs'
-import { buildTocModel } from './content-model'
-import { buildDashboard } from './dashboard-spec'
 import { renderKatex } from './katex';
 import { lightbox } from './lightbox'
 // Note: the tablesort lib is not ESM friendly, and the sorts expect `Tablesort` to be available on the global
@@ -48,9 +45,6 @@ function initTocScrollSpy () {
 }
 
 window.addEventListener('DOMContentLoaded', () => {
-  const model = buildTocModel('.markdown')
-  initToc({tocSelector:'.toc', model })
-  buildDashboard('#dashboard-container', model)
   initTocDepthSlider()
   initTocScrollSpy()
   initTableSort()

content/intro/_index.md

@@ -71,7 +71,8 @@ Each section of the spec must be stable and audited before it is considered done
 </table>
 
 ### Spec Status Overview
-<div id="dashboard-container"></div>
+
+{{<dashboard-spec>}}
 
 ### Spec Stabilization Progress
 

layouts/partials/single/menu-single.html

@@ -3,4 +3,5 @@
     <p class="label">TABLE OF CONTENTS</p>
     <input title="Adjust the depth of the toc" id="toc-depth-slider" type="range" step="1" min="1" max="5" value="2" style="width:174px" />
   </div>
+  {{ partial "toc" . }}
 </div>

layouts/partials/toc.html

@@ -0,0 +1,17 @@
+{{ define "toc-list" }}
+  {{ $depth := .depth }}
+  <ol class="depth-{{ .depth }}{{ if ge .depth 2 }} maybe-hide{{ end }}">
+    {{ range .children }}
+      <li>
+        <a href="#{{ .id }}">{{.text}}</a>
+        {{ if gt (len .children) 0 }}
+          {{ template "toc-list" (dict "children" .children "depth" (add 1 $depth) ) }}
+        {{ end }}
+      </li>
+    {{ end }}
+  </ol>
+{{ end }}
+
+{{ if isset .Site.Data "toc" }}
+  {{ template "toc-list" (dict "children" .Site.Data.toc "depth" 0 )}}
+{{ end }}

layouts/shortcodes/dashboard-spec.html

@@ -1,59 +1,69 @@
-{{- with .Site.GetPage "/" -}}
+{{ if isset .Site.Data "toc" }}
+  {{ template "dashboard-spec" (dict "children" .Site.Data.toc "number" 0 )}}
+{{ end }}
+
+{{ define "dashboard-spec" }}
 <table id="dashboard" class="sort Dashboard tablesort">
     <thead>
         <tr>
             <th>Section</th>
-            <th>Weight</th>
             <th>State</th>
             <th>Theory Audit</th>
         </tr>
     </thead>
     <tbody>
-        {{- template "dashboard-section-children" (dict "Section" . "level" 0) -}}
+        {{ range .children }}
+            {{- template "dashboard-spec-tr" . -}}
+        {{ end }}
     </tbody>
 </table>
-{{- end -}}
+{{ end }}
 
-<!-- Children Template -->
-{{ define "dashboard-section-children" }}
-    {{- $level := .level -}}
-    {{- $level = mul $level 10 -}}
-    {{- $pages := where .Section.Pages "Params.bookhidden" "ne" true -}}
-    {{- $pages2 := where $pages "Params.dashboardhidden" "ne" true -}}
-    {{- range sort $pages2 "Weight" "asc" -}}
-        {{- $level = add $level 1 -}}
-        {{- if (or (lt $level 200) (gt $level 10000)) -}}
-            {{ template "dashboard-section-children" (dict "Section" . "level" $level) }}
-        {{- else if .IsSection -}}
-            {{ template "dashboard-tr" (dict "Page" . "Level" $level) }}
-            {{ template "dashboard-section-children" (dict "Section" . "level" $level) }}
-        {{ else if and .IsPage .Content }}
-            {{ template "dashboard-tr" (dict "Page" . "Level" $level) }}
-        {{ end }}
+{{ define "stateToNumber" }}
+    {{- $num := 6 -}}
+    {{- if eq . "done" -}}{{$num = 1}}{{end}}
+    {{- if eq . "stable" -}}{{$num = 1}}{{end}}
+    {{- if eq . "reliable" -}}{{$num = 2}}{{end}}
+    {{- if eq . "wip" -}}{{$num = 3}}{{end}}
+    {{- if eq . "incorrect" -}}{{$num = 4}}{{end}}
+    {{- if eq . "missing" -}}{{$num = 5}}{{end}}
+    {{- $num -}}
+{{end}}
+
+{{ define "humanizeState" }}
+    {{- if eq . "wip" -}}
+    Draft/WIP
+    {{- else if eq . "n/a" -}}
+    {{ else }}
+        {{ humanize . }}
     {{ end }}
 {{ end }}
 
 <!-- Children TR template -->
-{{- define "dashboard-tr" -}}
+{{- define "dashboard-spec-tr" -}}
 <tr>
     <!-- Section -->
-    <td class="Dashboard-section">{{- delimit (split .Level "") "." }} 
-        {{ template "portable-link" (dict "Destination" .Page.File.Path "Text" .Page.Title "Page" .Page) }}
+    <td class="Dashboard-section">
+        {{.number}} <a href="#{{.id}}">{{.text}}</a>
     </td>
-
-    <!-- Weight -->
-    <td>{{- (default 0 .Page.Params.dashboardWeight) -}}</td>
 
     <!-- State -->
-    <td class="text-black bg-na bg-{{- .Page.Params.dashboardState }} ">
-        {{- if eq .Page.Params.dashboardState "wip" -}}
-            WIP
-        {{- else -}}
-            {{- (default "N/A" (humanize .Page.Params.dashboardState)) -}}
-        {{- end -}}
+    <td data-sort="{{template "stateToNumber" .dashboardState}}" class="text-black bg-na bg-{{.dashboardState}}">
+        {{ template "humanizeState" .dashboardState }}
     </td>
 
     <!-- Audit -->
-    <td class="text-transparent {{ if gt .Page.Params.dashboardaudit 0 }}bg-stable{{ else }}bg-incorrect{{end}}">{{ .Page.Params.dashboardaudit }}</td>
+    <td data-sort="{{template "stateToNumber" .dashboardAudit}}" class="text-black bg-{{.dashboardAudit}}">
+        {{- if eq .dashboardAuditURL "" -}}
+        {{ template "humanizeState" .dashboardAudit }} 
+        {{ else }}
+            <a href="{{ .dashboardAuditURL }}" title="Read the audit report" target="_blank" rel="noopener noreferrer" class="text-black">{{.dashboardAuditDate}}<i class="gg-external gg-s-half"></i></a>
+        {{ end }}
+    </td>
 </tr>
+{{ range .children }}
+    {{ if .page }}
+        {{- template "dashboard-spec-tr" . -}}
+    {{ end }}
+{{ end }}
 {{- end -}}

package.json

@@ -7,10 +7,11 @@
     "test": "remark content --quiet",
     "start": "concurrently npm:watch-*",
     "serve": "npm start",
-    "watch-hugo": "npm run build-diagrams && hugo server --bind=0.0.0.0 --disableFastRender",
-    "watch-diagrams": "tools/diagrams.js --watch",
-    "build": "npm run build-diagrams && hugo --gc --minify",
-    "build-diagrams": "tools/diagrams.js --all",
+    "watch-hugo": "npm run build-diagrams && hugo server --bind=0.0.0.0 --disableFastRender --renderToDisk",
+    "watch-assets": "tools/watch.js --watch",
+    "build": "npm run build-diagrams && hugo --quiet && npm run build-toc && hugo --gc --minify",
+    "build-diagrams": "tools/diagrams.js",
+    "build-toc": "tools/toc.js",
     "clean": "premove public resources static/_gen && hugo mod clean --all && hugo mod tidy",
     "release": "np --no-publish && conventional-github-releaser -p angular"
   },
@@ -41,6 +42,7 @@
     "globby": "^11.0.1",
     "graphviz-cli": "^1.0.0",
     "hugo-extended": "^0.74.3",
+    "jsdom": "^16.4.0",
     "np": "^6.5.0",
     "premove": "^3.0.1"
   }