Improve Table of Contents (#512)

Overhaul design and fix re-rendering issues. Also added suport for chapter expansion.

---------

Co-authored-by: Philippa Markovics <[email protected]>
Co-authored-by: Martin Kavalar <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -18,13 +18,14 @@ Changes can be:
 
 * 🚨 Rename `:nextjournal.clerk/opts` to `:nextjournal.clerk/render-opts` to clarify this options map is available as the second arg to parametrize the `:render-fn`. Still support the `:nextjournal.clerk/opts` for now.
 
+* 📖 Improve Table of Contents design and fixing re-rendering issues. Also added suport for chapter expansion.
+
 * 💫 Assign `:name` to every viewer in `default-viewers`
 
 * 🐞 Don't run existing files through `fs/glob`, fixes [#504](https://github.com/nextjournal/clerk/issues/504). Also improves performance of homepage.
 
 * 🐞 Show correct non-var return value for deflike form, fixes [#499](https://github.com/nextjournal/clerk/issues/499)
 
-
 ## 0.14.919 (2023-06-13)
 
 * 🚨 Breaking Changes:

notebooks/cherry.clj

@@ -1,6 +1,7 @@
-;; # Compile viewer functions using cherry
+;; # 🍒 Compile viewer functions using cherry
 (ns cherry
-  {:nextjournal.clerk/render-evaluator :cherry}
+  {:nextjournal.clerk/render-evaluator :cherry
+   :nextjournal.clerk/toc true}
   (:require [nextjournal.clerk :as clerk]
             [nextjournal.clerk.viewer :as viewer]))
 
@@ -19,7 +20,7 @@
                      (pr-str (interleave (cycle [1]) (frequencies [1 2 3 1 2 3])))))])
   {:nextjournal.clerk/render-evaluator :sci} nil)
 
-;; Better performance:
+;; ## ⏱️ Better performance:
 
 (clerk/with-viewer
   '(fn [value]
@@ -54,7 +55,7 @@
                                     :key "id" :fields ["rate"]}}]
    :projection {:type "albersUsa"} :mark "geoshape" :encoding {:color {:field "rate" :type "quantitative"}}})
 
-;; ## Input text and compile on the fly with cherry
+;; ## 🔨 Input text and compile on the fly with cherry
 
 (clerk/with-viewer
   {;; :evaluator :cherry
@@ -80,15 +81,15 @@
   {:nextjournal.clerk/render-evaluator :cherry}
   nil)
 
-;; ## Functions defined with `defn` are part of the global context
+;; ## 🌍 Functions defined with `defn` are part of the global context
 
 ;; (for now) and can be called in successive expressions
 
 (clerk/eval-cljs-str "(defn foo [x] (this-as this (inc x)))")
 
 (clerk/eval-cljs-str "(foo 1)")
 
-;; ## Async/await works cherry
+;; ## 🚦Async/await works cherry
 
 ;; Here we dynamically import a module, await its value and then pull out the
 ;; default function, which we expose as a global function. Because s-expressions
@@ -112,7 +113,7 @@
      [nextjournal.clerk.render/render-promise
       (emoji-picker)]) nil)
 
-;; ## Macros
+;; ## 🧩 Macros
 
 (clerk/eval-cljs
  '(defn clicks []
@@ -123,7 +124,7 @@
 
 (clerk/with-viewer '(fn [_] (this-as this [clicks])) nil)
 
-;; ## Evaluator option as form metadata
+;; ## 👻 Evaluator option as form metadata
 ^{::clerk/visibility {:code :hide :result :hide} ::clerk/no-cache true}
 (clerk/add-viewers! [(assoc viewer/code-block-viewer :transform-fn (viewer/update-val :text))])
 

notebooks/document_linking.clj

@@ -1,7 +1,9 @@
 ;; # 🖇️ Document Linking
 (ns document-linking
+  {:nextjournal.clerk/toc true}
   (:require [nextjournal.clerk :as clerk]))
 
+;; ## `clerk/doc-url` helper
 ;; The helper `clerk/doc-url` allows to reference notebooks by path. We currently support relative paths with respect to the directory which started the Clerk application. An optional trailing hash fragment can appended to the path in order for the page to be scrolled up to the indicated identifier.
 (clerk/html
  [:ol
@@ -12,6 +14,8 @@
   [:li [:a {:href (clerk/doc-url "book.clj")} "The 📕Book"]]
   [:li [:a {:href (clerk/doc-url "")} "Homepage"]]])
 
+
+;; ## Client Side
 ;; The same functionality is available in the SCI context when building render functions.
 (clerk/with-viewer
   '(fn [_ _]

notebooks/how_clerk_works.clj

@@ -1,6 +1,6 @@
 ;; # How Clerk Works 🕵🏻‍♀️
-^{:nextjournal.clerk/toc true}
 (ns how-clerk-works
+  {:nextjournal.clerk/toc true}
   (:require [next.jdbc :as jdbc]
             [nextjournal.clerk :as clerk]
             [nextjournal.clerk.parser :as parser]

notebooks/meta_toc.clj

@@ -0,0 +1,47 @@
+;; # 📕 Meta Table of Contents
+(ns meta-toc
+  {:nextjournal.clerk/toc true}
+  (:require [nextjournal.clerk :as clerk]
+            [nextjournal.clerk.parser :as parser]
+            [nextjournal.markdown.transform :as md.transform]
+            [nextjournal.clerk.viewer :as v]))
+
+;; This assembles the table of contents programmatically from a
+;; collection of notebooks.
+
+;; ## Notebooks
+(def notebooks
+  ["notebooks/how_clerk_works.clj"
+   "notebooks/cherry.clj"
+   "notebooks/tracer.clj"
+   "notebooks/document_linking.clj"])
+
+(defn md-toc->navbar-items [current-notebook file {:keys [children]}]
+  (mapv (fn [{:as item :keys [emoji attrs]}]
+          {:title (md.transform/->text item)
+           :expanded? (= current-notebook file)
+           :scroll-to-anchor? false
+           :emoji emoji
+           :path (clerk/doc-url file (:id attrs))
+           :items (md-toc->navbar-items current-notebook file item)}) children))
+
+(defn meta-toc [current-notebook paths]
+  (into []
+        (mapcat (comp (fn [{:keys [toc file]}] (md-toc->navbar-items current-notebook file toc))
+                      (partial parser/parse-file {:doc? true})))
+        paths))
+
+(def book-viewer
+  (update v/notebook-viewer
+          :transform-fn (fn [original-transform]
+                          (fn [wrapped-value]
+                            (-> wrapped-value
+                                original-transform
+                                (assoc :nextjournal/opts {:expandable? true})
+                                (assoc-in [:nextjournal/value :toc]
+                                          (meta-toc (:file (v/->value wrapped-value)) notebooks)))))))
+
+#_(clerk/add-viewers! [book-viewer])
+
+;; Test actual cross-doc toc
+(clerk/add-viewers! [book-viewer])

notebooks/profile.clj

@@ -17,11 +17,15 @@
 
 
 
-(do (time (analyzer/build-graph analyzed)) :done)
+(time
+ (prof/profile (dotimes [_ 10]
+                 (analyzer/build-graph analyzed))))
 
 
 
-(prof/profile (analyzer/build-graph analyzed))
+(prof/profile
+ (dotimes [_ 10]
+   (nextjournal.clerk/show! "notebooks/rule_30.clj")))
 
 (prof/profile (analyzer/build-graph analyzed))
 

notebooks/tracer.clj

@@ -1,6 +1,8 @@
 ;; # 👩🏻‍💻 Show the code
-^{:nextjournal.clerk/visibility {:code :hide}}
+
 (ns tracer
+  {:nextjournal.clerk/visibility {:code :hide}
+   :nextjournal.clerk/toc true}
   (:require [nextjournal.clerk :as clerk]))
 
 ;; ## Tracer

package.json

@@ -18,7 +18,7 @@
     "@nextjournal/lezer-clojure": "1.0.0",
     "d3-require": "^1.2.4",
     "emoji-regex": "^10.0.0",
-    "framer-motion": "^6.2.8",
+    "framer-motion": "^10.12.16",
     "katex": "^0.12.0",
     "lezer-clojure": "1.0.0-rc.2",
     "markdown-it": "^12.2.0",

src/nextjournal/clerk/analyzer.clj

@@ -379,7 +379,7 @@
      (or (when-let [{:as cached-analysis :keys [file-sha]} (@!file->analysis-cache file)]
            (when (= file-sha current-file-sha)
              cached-analysis))
-         (let [analysis (analyze-doc {:file-sha current-file-sha} (parser/parse-file {} file))]
+         (let [analysis (analyze-doc {:file-sha current-file-sha :graph (dep/graph)} (parser/parse-file {} file))]
            (swap! !file->analysis-cache assoc file analysis)
            analysis))))
   ([state file]

src/nextjournal/clerk/builder.clj

@@ -36,6 +36,7 @@
          "fragments"
          "hiding_clerk_metadata"
          "js_import"
+         "meta_toc"
          "multiviewer"
          "pagination"
          "paren_soup"