Make following clerk/doc-url links usable in interactive mode (#437)

zampino · mk · philippamarkovics · web-flow · commit 2511b226c78d · 2023-04-21T10:41:56.000+02:00
Support following `clerk/doc-url` links in interactive mode. Previously these links would only be functional in the static build. Update the browser url accordingly and support evaluating a given doc by entering it in the browser's address bar.

Also perform an internal refactor to drop the `!error` state atoms in both the webserver and render namespaces and store that state under a key in the `!doc` atom instead.

Change `nextjournal.clerk.render/clerk-eval` to not recompute the currently shown document when using the 1-arity version. Added a second arity that takes an opts map with a `:recompute?` key.

Co-authored-by: Martin Kavalar &lt;martin@nextjournal.com&gt;
Co-authored-by: Philippa Markovics &lt;philippa@markovics.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 Changes can be:
 * 🌟⭐️💫 features
+* 🚨 possibly breaking
 * 🐞🐜 friendly or nasty bugs
 * 🛠 dev improvements
 
@@ -13,8 +14,14 @@ Changes can be:
 
 * 🍕 `clerk/fragment` for splicing a seq of values into the document as if it were produced by results of individual cells. Useful when programmatically generating content.
 
+* 🔗 Support following `clerk/doc-url` links in interactive mode. Previously these links would only be functional in the static build. Update the browser url accordingly and support evaluating a given doc by entering it in the browser's address bar.
+
+* 🚨 Change `nextjournal.clerk.render/clerk-eval` to not recompute the currently shown document when using the 1-arity version. Added a second arity that takes an opts map with a `:recompute?` key.
+
 * 🔌 Make websocket reconnect automatically on close to avoid having to reload the page
+
 * 💫 Cache expressions that return `nil` in memory
+
 * 🐜 Ensure custom `print-method` supporting unreadable symbols preserves metadata
 
 ## 0.13.842 (2023-03-07)
diff --git a/README.md b/README.md
@@ -151,4 +151,3 @@ You can use the following BibTeX citation:
   year         = 2023
 }
 ```
-
diff --git a/book.clj b/book.clj
@@ -457,9 +457,8 @@ v/default-viewers
 
 
 ^{::clerk/visibility {:code :fold :result :hide}}
-(do
-  (set! *print-namespace-maps* false)
-  (defn show-raw-value [x]
+(defn show-raw-value [x]
+  (binding [*print-namespace-maps* false]
     (clerk/code (with-out-str (clojure.pprint/pprint x)))))
 
 ;; Let's start with one of the simplest examples. You can see that
diff --git a/deps.edn b/deps.edn
@@ -24,7 +24,7 @@
 
         juji/editscript {:mvn/version "0.6.2"}}
 
- :aliases {:nextjournal/clerk {:extra-deps {org.clojure/clojure {:mvn/version "1.11.1"} ;; for `:as-alias` support in static build
+ :aliases {:nextjournal/clerk {:extra-deps {org.clojure/clojure {:mvn/version "1.12.0-alpha3"} ;; for `:as-alias` support in static build
                                             org.slf4j/slf4j-nop {:mvn/version "1.7.36"}
                                             org.babashka/cli {:mvn/version "0.6.50"}}
                                :extra-paths ["notebooks"]
diff --git a/notebooks/clerk_eval.clj b/notebooks/clerk_eval.clj
@@ -2,20 +2,19 @@
 (ns clerk-eval
   {:nextjournal.clerk/visibility {:code :fold}}
   (:require [nextjournal.clerk :as clerk]
-            [nextjournal.clerk.render.hooks :as-alias hooks]
             [nextjournal.clerk.viewer :as v]))
 
 (clerk/with-viewer
   '(fn [code-str _]
-     (let [!code (hooks/use-state code-str)
-           !result (hooks/use-state nil)]
+     (let [!code (nextjournal.clerk.render.hooks/use-state code-str)
+           !result (nextjournal.clerk.render.hooks/use-state nil)]
        [:div
         [:p "Enter a form to be evaluated using " [:code "v/clerk-eval"] ":"]
         [:div.flex.mb-4
          [:div.shadow-inner.border.rounded.bg-slate-100.px-2.py-1.flex-auto
           [nextjournal.clerk.render.code/editor !code]]
          [:button.rounded.px-3.py-1.bg-indigo-600.text-white.font-sans.font-bold.ml-2
-          {:on-click #(reset! !result (v/clerk-eval (read-string @!code)))}
+          {:on-click #(reset! !result (nextjournal.clerk.render/clerk-eval (read-string @!code)))}
           "eval!"]]
         (when @!result
           [nextjournal.clerk.render/inspect @!result])]))
diff --git a/notebooks/dice.clj b/notebooks/dice.clj
@@ -15,7 +15,7 @@
                      (when side
                        [:div.mt-2 {:style {:font-size "6em"}} side])
                      [:button.bg-blue-500.hover:bg-blue-700.text-white.font-bold.py-2.px-4.rounded
-                      {:on-click (fn [e] (nextjournal.clerk.render/clerk-eval '(roll!)))} "Roll 🎲!"]])}
+                      {:on-click (fn [e] (nextjournal.clerk.render/clerk-eval {:recompute? true} '(roll!)))} "Roll 🎲!"]])}
 @dice
 
 ;; Our roll! function `resets!` our `dice` with a random side and prints and says the result. Finally it updates the notebook.
diff --git a/notebooks/document_linking.clj b/notebooks/document_linking.clj
@@ -0,0 +1,21 @@
+;; # 🖇️ Document Linking
+(ns document-linking
+  (:require [nextjournal.clerk :as clerk]))
+
+;; 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
+  [:li [:a {:href (clerk/doc-url "notebooks/viewers/html.clj")} "HTML"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/viewers/image.clj")} "Images"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/markdown.md" "appendix")} "Markdown / Appendix"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/how_clerk_works.clj" "step-3:-analyzer")} "Clerk Analyzer"]]
+  [:li [:a {:href (clerk/doc-url "book.clj")} "The 📕Book"]]
+  [:li [:a {:href (clerk/doc-url "")} "Homepage"]]])
+
+;; The same functionality is available in the SCI context when building render functions.
+(clerk/with-viewer
+  '(fn [_ _]
+     [:ol
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewers/html.clj")} "HTML"]]
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/markdown.md")} "Markdown"]]
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewer_api.clj")} "Viewer API / Tables"]]]) nil)
diff --git a/notebooks/viewers/html.clj b/notebooks/viewers/html.clj
@@ -17,11 +17,11 @@
 
 (clerk/with-viewer
   '(fn [_ _] [:div
-              "Go to "
-              [:a.text-lg {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewers/image.clj")} "images"]
-              " notebook."]) nil)
+             "Go to "
+             [:a.text-lg {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewers/image.clj")} "images"]
+             " notebook."]) nil)
 
 (clerk/html
- [:ol (list [:li "One"]
-            [:li "Two"]
-            [:li "Three"])])
+ [:ol (list [:li [:a {:href (clerk/doc-url "notebooks/document_linking.clj")} "Cross Document Linking"]]
+            [:li [:a {:href (clerk/doc-url "notebooks/rule_30.clj")} "Rule 30"]]
+            [:li [:a {:href (clerk/doc-url "notebooks/markdown.md")} "Appendix"]])])
diff --git a/src/nextjournal/clerk.clj b/src/nextjournal/clerk.clj
@@ -30,37 +30,46 @@
   (nextjournal.clerk/show! \"https://raw.githubusercontent.com/nextjournal/clerk-demo/main/notebooks/rule_30.clj\")
   (nextjournal.clerk/show! (java.io.StringReader. \";; # Notebook from String 👋\n(+ 41 1)\"))
   "
-  [file-or-ns]
-  (if config/*in-clerk*
-    ::ignored
-    (try
-      (webserver/set-status! {:progress 0 :status "Parsing…"})
-      (let [file (cond
-                   (nil? file-or-ns)
-                   (throw (ex-info (str "`nextjournal.clerk/show!` cannot show `nil`.")
-                                   {:file-or-ns file-or-ns}))
-
-                   (or (symbol? file-or-ns) (instance? clojure.lang.Namespace file-or-ns))
-                   (or (some (fn [ext]
-                               (io/resource (str (str/replace (namespace-munge file-or-ns) "." "/") ext)))
-                             [".clj" ".cljc"])
-                       (throw (ex-info (str "`nextjournal.clerk/show!` could not find a resource on the classpath for: `" (pr-str file-or-ns) "`")
-                                       {:file-or-ns file-or-ns})))
-
-                   :else
-                   file-or-ns)
-            doc (try (parser/parse-file {:doc? true} file)
-                     (catch java.io.FileNotFoundException _e
-                       (throw (ex-info (str "`nextjournal.clerk/show!` could not find the file: `" (pr-str file-or-ns) "`")
-                                       {:file-or-ns file-or-ns}))))
-            _ (reset! !last-file file)
-            {:keys [blob->result]} @webserver/!doc
-            {:keys [result time-ms]} (eval/time-ms (eval/+eval-results blob->result (assoc doc :set-status-fn webserver/set-status!)))]
-        (println (str "Clerk evaluated '" file "' in " time-ms "ms."))
-        (webserver/update-doc! result))
-      (catch Exception e
-        (webserver/show-error! e)
-        (throw e)))))
+  ([file-or-ns] (show! {} file-or-ns))
+  ([opts file-or-ns]
+   (if config/*in-clerk*
+     ::ignored
+     (try
+       (webserver/set-status! {:progress 0 :status "Parsing…"})
+       (let [file (cond
+                    (nil? file-or-ns)
+                    (throw (ex-info (str "`nextjournal.clerk/show!` cannot show `nil`.")
+                                    {:file-or-ns file-or-ns}))
+
+                    (or (symbol? file-or-ns) (instance? clojure.lang.Namespace file-or-ns))
+                    (or (some (fn [ext]
+                                (io/resource (str (str/replace (namespace-munge file-or-ns) "." "/") ext)))
+                              [".clj" ".cljc"])
+                        (throw (ex-info (str "`nextjournal.clerk/show!` could not find a resource on the classpath for: `" (pr-str file-or-ns) "`")
+                                        {:file-or-ns file-or-ns})))
+
+                    :else
+                    file-or-ns)
+             doc (try (merge opts
+                             {:nav-path (webserver/->nav-path file-or-ns)}
+                             (parser/parse-file {:doc? true} file))
+                      (catch java.io.FileNotFoundException _e
+                        (throw (ex-info (str "`nextjournal.clerk/show!` could not find the file: `" (pr-str file-or-ns) "`")
+                                        {:file-or-ns file-or-ns})))
+                      (catch Exception e
+                        (throw (ex-info (str "`nextjournal.clerk/show!` could not not parse the file: `" (pr-str file-or-ns) "`")
+                                        {::doc {:file file-or-ns}}
+                                        e))))
+             _ (reset! !last-file file)
+             {:keys [blob->result]} @webserver/!doc
+             {:keys [result time-ms]} (try (eval/time-ms (eval/+eval-results blob->result (assoc doc :set-status-fn webserver/set-status!)))
+                                           (catch Exception e
+                                             (throw (ex-info (str "`nextjournal.clerk/show!` encountered an eval error with: `" (pr-str file-or-ns) "`") {::doc doc} e))))]
+         (println (str "Clerk evaluated '" file "' in " time-ms "ms."))
+         (webserver/update-doc! result))
+       (catch Exception e
+         (webserver/update-doc! (assoc (-> e ex-data ::doc) :error e))
+         (throw e))))))
 
 #_(show! "notebooks/exec_status.clj")
 #_(clear-cache!)
@@ -373,7 +382,7 @@
   "Experimental notebook viewer. You probably should not use this."
   (partial with-viewer (:name v/notebook-viewer)))
 
-(defn doc-url [path] (v/doc-url path))
+(defn doc-url [& args] (apply v/doc-url args))
 
 (defmacro example
   "Evaluates the expressions in `body` showing code next to results in Clerk.
diff --git a/src/nextjournal/clerk/builder.clj b/src/nextjournal/clerk/builder.clj
@@ -284,11 +284,14 @@
       (fs/delete-tree tw-folder)
       (update opts :resource->url assoc "/css/viewer.css" url))))
 
-(defn doc-url [{:as opts :keys [bundle?]} docs file path]
-  (let [url (get (build-path->url opts docs) path)]
-    (if bundle?
-      (str "#/" url)
-      (str (viewer/relative-root-prefix-from (viewer/map-index opts file)) url))))
+(defn doc-url
+  ([opts doc file path] (doc-url opts doc file path nil))
+  ([{:as opts :keys [bundle?]} docs file path fragment]
+   (let [url (get (build-path->url opts docs) path)]
+     (if bundle?
+       (str "#/" url)
+       (str (viewer/relative-root-prefix-from (viewer/map-index opts file))
+            url (when fragment (str "#" fragment)))))))
 
 (defn build-static-app! [{:as opts :keys [bundle?]}]
   (let [{:as opts :keys [download-cache-fn upload-cache-fn report-fn compile-css? expanded-paths error]}
diff --git a/src/nextjournal/clerk/home.clj b/src/nextjournal/clerk/home.clj
@@ -0,0 +1,46 @@
+(ns nextjournal.clerk.home
+  {:nextjournal.clerk/visibility {:code :hide :result :hide}}
+  (:require [clojure.string :as str]
+            [babashka.fs :as fs]
+            [nextjournal.clerk :as clerk]))
+
+(defn glob-notebooks []
+  (let [ignored-paths (into #{} (map fs/path) #{"node_modules" "target"})]
+    (into []
+          (remove #(some ignored-paths (fs/components %)))
+          (fs/glob "." "**.{clj,md}"))))
+
+^::clerk/no-cache
+(def !notebooks
+  (atom (glob-notebooks)))
+
+{::clerk/visibility {:result :show}}
+
+^{::clerk/css-class ["w-full" "m-0"]}
+(clerk/html
+ [:div.max-w-prose.px-8.mx-auto
+  [:div.md:flex.md:justify-between.px-8.text-center.md:text-left
+   [:h1 "👋 Welcome to Clerk!"]
+   #_[:div.text-sm.md:text-xs.font-sans.md:text-right.mt-1
+      [:span.font-bold.block
+       "You’re running Clerk " [:a {:href "#"} "v0.12.707"] "."]
+      [:span "The newest version is " [:a {:href "#"} "v0.12.707"] ". " [:a {:href "#"} "What’s changed?"]]]]
+  [:div.rounded-lg.border-2.border-amber-100.bg-amber-50.px-8.pt-3.pb-4.mx-auto.text-center.font-sans.mt-6.md:mt-4
+   [:div.font-medium
+    "Call " [:span.font-mono.text-sm.bg-white.bg-opacity-80.mx-1.font-bold "nextjournal.clerk/show!"]
+    " from your REPL to make a notebook appear!"]
+   [:div.mt-2.text-sm "⚡️ This works best when you " [:a {:href "https://book.clerk.vision/#editor-integration"} "set up your editor to use a key binding for this!"]]]
+  [:div.rounded-lg.border-2.border-indigo-100.bg-indigo-50.px-8.pt-3.pb-4.mt-6.text-center.font-sans
+   [:div.font-medium "📖 New to Clerk? Learn all about it in " [:a {:href "https://book.clerk.vision"} "The Book of Clerk"] "."]
+   #_
+   [:div.mt-2.text-sm
+    "Here are some handy links:"
+    [:a.ml-3 {:href "#"} "🚀 Getting Started"]
+    [:a.ml-3 {:href "#"} "🔍 Viewers"]
+    [:a.ml-3 {:href "#"} "🙈 Controlling Visibility"]]]
+  [:h4 "Your notebooks"]
+  (into [:div.md:columns-3.gap-8.font-sans.text-sm]
+        (map (fn [path]
+               [:div [:a {:href (clerk/doc-url (str path))} (fs/file-name path)]]))
+        @!notebooks)])
+
diff --git a/src/nextjournal/clerk/render.cljs b/src/nextjournal/clerk/render.cljs
diff --git a/src/nextjournal/clerk/sci_env.cljs b/src/nextjournal/clerk/sci_env.cljs
diff --git a/src/nextjournal/clerk/viewer.cljc b/src/nextjournal/clerk/viewer.cljc
diff --git a/src/nextjournal/clerk/webserver.clj b/src/nextjournal/clerk/webserver.clj
diff --git a/test/nextjournal/clerk/webserver_test.clj b/test/nextjournal/clerk/webserver_test.clj

Original file line number	Diff line number	Diff line change
`@@ -151,4 +151,3 @@ You can use the following BibTeX citation:`
`151`	`151`	`year = 2023`
`152`	`152`	`}`
`153`	`153`	```
`154`		`-`