Unify link handling between build! and serve! (#529)

This unifies the link handling between `build!` and `serve!` by no longer using extensions in either mode (was `.clj|md` in `serve!` and `.html` in `build!`). 

To support this in the unbundled static build, we're now writing directories with `index.html` for each notebook. This makes links in this build no longer accessible without a http server. If you're looking for a self-contained html that works without a webserver, set the `:bundle` option.

Author: mk

CHANGELOG.md

@@ -32,6 +32,12 @@ Changes can be:
   * `nextjournal.clerk.viewer/html` instead.
 
   Also rename `nextjournal.clerk.render/html-render` to `nextjournal.clerk.render/render-html` and make `nextjournal.clerk.viewer/html` use it when called from a reactive context.
+  
+* 🚨 Unify the link handling between `build!` and `serve!` 
+
+  By no longer using extensions in either mode (was `.clj|md` in `serve!` and `.html` in `build!`).
+  
+  To support this in the unbundled static build, we're now writing directories with `index.html` for each notebook. This makes links in this build no longer accessible without a http server. If you're looking for a self-contained html that works without a webserver, set the `:bundle` option.
 
 * 📖 Improve Table of Contents design and fixing re-rendering issues. Also added suport for chapter expansion.
 

index.clj

@@ -8,5 +8,6 @@
 (clerk/html
  [:div.viewer-markdown
   [:ul
-   [:li [:a.underline {:href (clerk/doc-url "notebooks/rule_30.clj")} "Rule 30"]]
-   [:li [:a.underline {:href (clerk/doc-url "notebooks/markdown.md")} "Markdown"]]]])
+   [:li [:a.underline {:href (clerk/doc-url "notebooks/rule_30")} "Rule 30"]]
+   [:li [:a.underline {:href (clerk/doc-url "notebooks/links")} "Link Design"]]
+   [:li [:a.underline {:href (clerk/doc-url "notebooks/markdown")} "Markdown"]]]])

notebooks/document_linking.clj

@@ -7,11 +7,11 @@
 ;; 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/viewers/html")} "HTML"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/viewers/image")} "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 "notebooks/how_clerk_works" "step-3:-analyzer")} "Clerk Analyzer"]]
+  [:li [:a {:href (clerk/doc-url "book")} "The 📕Book"]]
   [:li [:a {:href (clerk/doc-url "")} "Homepage"]]])
 
 
@@ -20,6 +20,6 @@
 (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)
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewers/html")} "HTML"]]
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/markdown")} "Markdown"]]
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewer_api")} "Viewer API / Tables"]]]) nil)

notebooks/links.md

@@ -0,0 +1,67 @@
+# Links
+```clojure
+(ns links
+  {:nextjournal.clerk/toc true}
+  (:require [nextjournal.clerk :as clerk]))
+```
+## Design
+
+We have three different modes to consider for links:
+
+1. Interactive mode `serve!`
+2. Static build unbundled `(build! {:bundle false})`
+3. Static build bundled `(build! {:bundle true})`
+
+The behaviour when triggering links we want is:
+
+1. Interactive mode: trigger a js event `(clerk-eval 'nextjournal.clerk.webserver/navigate! ,,,)`, the doc will in turn be updated via the websocket
+2. Static build unbundled: not intercept the link, let the browser perform its normal navigation
+3. Static build bundled: trigger a js event to update the doc, update the browser's hash so the doc state is persisted on reload
+
+We can allow folks to write normal (relative) links. The limitations here being that things like open in new tab would not work and we can't support a routing function. Both these limitations means we probably want to continue encouraging the use of a helper like `clerk/doc-url` going forward.
+
+We currently don't support navigating to headings / table of contents sections in the bundled build. This could be supported however by introducing a way to encode that in the hash e.g. with `#page:section`.
+
+
+## Examples
+
+
+### JVM-Side
+
+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.
+
+
+```clojure
+(clerk/html
+ [:ol
+  [:li [:a {:href (clerk/doc-url 'nextjournal.clerk.home)} "Home"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/viewers/html")} "HTML"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/viewers/image")} "Images"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/markdown.md" "appendix")} "Markdown / Appendix"]]
+  [:li [:a {:href (clerk/doc-url "notebooks/how_clerk_works" "step-3:-analyzer")} "Clerk Analyzer"]]
+  [:li [:a {:href (clerk/doc-url "book")} "The 📕Book"]]
+  [:li [:a {:href (clerk/doc-url "")} "Homepage"]]])
+```
+
+### Render
+
+The same functionality is available in the SCI context when building render functions.
+
+```clojure
+(clerk/with-viewer
+  '(fn [_ _]
+     [:ol
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewers/html")} "HTML"]]
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/markdown")} "Markdown"]]
+      [:li [:a {:href (nextjournal.clerk.viewer/doc-url "notebooks/viewer_api")} "Viewer API / Tables"]]]) nil)
+
+```
+
+
+### Inside Markdown
+
+Links should work inside markdown as well.
+
+* [HTML](../notebooks/viewers/html) (relative link)
+* [HTML](clerk/doc-url,"notebooks/viewers/html") (doc url, currently not functional)
+

src/nextjournal/clerk/builder.clj

@@ -205,6 +205,9 @@
       (expand-paths {:paths-fn `my-paths}))
 #_(expand-paths {:paths ["notebooks/viewers**"]})
 
+(def builtin-index
+  (io/resource "nextjournal/clerk/index.clj"))
+
 (defn process-build-opts [{:as opts :keys [paths index expand-paths?]}]
   (merge {:out-path default-out-path
           :bundle? false
@@ -223,29 +226,19 @@
                  (assoc :index (first expanded-paths))
                  (and (not index) (< 1 (count expanded-paths)) (every? (complement #{"index.clj"}) expanded-paths))
                  (as-> opts
-                   (let [index (io/resource "nextjournal/clerk/index.clj")]
-                     (-> opts (assoc :index index) (update :expanded-paths conj index)))))))))
+                     (-> opts (assoc :index builtin-index) (update :expanded-paths conj builtin-index))))))))
 
 #_(process-build-opts {:index 'book.clj :expand-paths? true})
 #_(process-build-opts {:paths ["notebooks/rule_30.clj"] :expand-paths? true})
 #_(process-build-opts {:paths ["notebooks/rule_30.clj"
                                "notebooks/markdown.md"] :expand-paths? true})
 
-(defn build-path->url [{:as opts :keys [bundle?]} docs]
-  (into {}
-        (map (comp (juxt identity #(cond-> (->> % (viewer/map-index opts) strip-index) (not bundle?) ->html-extension))
-                   str :file))
-        docs))
-#_(build-path->url {:bundle? false} [{:file "notebooks/foo.clj"} {:file "index.clj"}])
-#_(build-path->url {:bundle? true}  [{:file "notebooks/foo.clj"} {:file "index.clj"}])
-
 (defn build-static-app-opts [{:as opts :keys [bundle? out-path browse? index]} docs]
-  (let [path->doc (into {} (map (juxt (comp str :file) :viewer)) docs)]
+  (let [path->doc (into {} (map (juxt (comp str fs/strip-ext strip-index (partial viewer/map-index opts) :file) :viewer)) docs)]
     (assoc opts
            :bundle? bundle?
            :path->doc path->doc
-           :paths (vec (keys path->doc))
-           :path->url (build-path->url opts docs))))
+           :paths (vec (keys path->doc)))))
 
 (defn ssr!
   "Shells out to node to generate server-side-rendered html."
@@ -268,28 +261,30 @@
 
 (defn cleanup [build-opts]
   (select-keys build-opts
-               [:bundle? :path->doc :path->url :current-path :resource->url :exclude-js? :index :html]))
+               [:bundle? :path->doc :current-path :resource->url :exclude-js? :index :html]))
 
 (defn write-static-app!
   [opts docs]
-  (let [{:as opts :keys [bundle? out-path browse? ssr?]} (process-build-opts opts)
+  (let [{:keys [bundle? out-path browse? ssr?]} opts
         index-html (str out-path fs/file-separator "index.html")
-        {:as static-app-opts :keys [path->url path->doc]} (build-static-app-opts (viewer/update-if opts :index str) docs)]
-    (when-not (contains? (-> path->url vals set) "")
-      (throw (ex-info "Index must have been processed at this point" {:opts opts :docs docs})))
+        {:as static-app-opts :keys [path->doc]} (build-static-app-opts opts docs)]
+    (when-not (contains? (set (keys path->doc)) "")
+      (throw (ex-info "Index must have been processed at this point" {:static-app-opts static-app-opts})))
     (when-not (fs/exists? (fs/parent index-html))
       (fs/create-dirs (fs/parent index-html)))
     (if bundle?
       (spit index-html (view/->html (cleanup static-app-opts)))
       (doseq [[path doc] path->doc]
-        (let [out-html (str out-path fs/file-separator (->> path (viewer/map-index opts) ->html-extension))]
+        (let [out-html (fs/file out-path path "index.html")]
           (fs/create-dirs (fs/parent out-html))
           (spit out-html (view/->html (-> static-app-opts
                                           (assoc :path->doc (hash-map path doc) :current-path path)
                                           (cond-> ssr? ssr!)
                                           cleanup))))))
     (when browse?
-      (browse/browse-url (-> index-html fs/absolutize .toString path-to-url-canonicalize)))
+      (browse/browse-url (if-let [{:keys [port]} (and (= out-path "public/build") @webserver/!server)]
+                           (str "http://localhost:" port "/build/")
+                           (-> index-html fs/absolutize .toString path-to-url-canonicalize))))
     {:docs docs
      :index-html index-html
      :build-href (if (and @webserver/!server (= out-path default-out-path)) "/build/" index-html)}))
@@ -331,13 +326,13 @@
       (update opts :resource->url assoc "/css/viewer.css" 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 (viewer/update-if opts :index str) docs) path)]
-     (if bundle?
-       (str "#/" url)
-       (str (viewer/relative-root-prefix-from (viewer/map-index opts file))
-            url (when fragment (str "#" fragment)))))))
+  ([opts file path] (doc-url opts file path nil))
+  ([opts file path fragment]
+   (if (:bundle? opts)
+     (cond-> (str "#/" path)
+       fragment (str ":" fragment))
+     (str (viewer/relative-root-prefix-from (viewer/map-index opts file)) path
+          (when fragment (str "#" fragment))))))
 
 (defn read-opts-from-deps-edn! []
   (if (fs/exists? "deps.edn")
@@ -395,10 +390,14 @@
                                                                 (try
                                                                   (binding [*ns* *ns*
                                                                             *build-opts* opts
-                                                                            viewer/doc-url (partial doc-url opts state file)]
+                                                                            viewer/doc-url (partial doc-url opts file)]
                                                                     (let [doc (eval/eval-analyzed-doc doc)]
-                                                                      (assoc doc :viewer (view/doc->viewer (assoc opts :static-build? true
-                                                                                                                  :nav-path (str file)) doc))))
+                                                                      (assoc doc :viewer (view/doc->viewer (assoc opts
+                                                                                                                  :static-build? true
+                                                                                                                  :nav-path (if (instance? java.net.URL file)
+                                                                                                                              (str "'" (:ns doc))
+                                                                                                                              (str file)))
+                                                                                                           doc))))
                                                                   (catch Exception e
                                                                     {:error e})))]
                         (report-fn (merge {:stage :built :duration duration :idx idx}
@@ -422,8 +421,11 @@
 
 (comment
   (build-static-app! {:paths clerk-docs :bundle? true})
-  (build-static-app! {:paths ["notebooks/index.clj" "notebooks/rule_30.clj" "notebooks/viewer_api.md"] :index "notebooks/index.clj"})
-  (build-static-app! {:paths ["index.clj" "notebooks/rule_30.clj" "notebooks/markdown.md"] :bundle? false :browse? false})
+  (build-static-app! {:paths ["notebooks/editor.clj"] :browse? true})
+  (build-static-app! {:paths ["CHANGELOG.md" "notebooks/editor.clj"] :browse? true})
+  (build-static-app! {:paths ["index.clj" "notebooks/links.md" "notebooks/rule_30.clj" "notebooks/markdown.md"] :bundle? true :browse? true})
+  (build-static-app! {:paths ["notebooks/links.md" "notebooks/rule_30.clj" "notebooks/markdown.md"] :bundle? true :browse? true})
+  (build-static-app! {:paths ["index.clj" "notebooks/rule_30.clj" "notebooks/markdown.md"] :bundle? false :browse? true})
   (build-static-app! {:paths ["notebooks/viewers/**"]})
   (build-static-app! {:index "notebooks/rule_30.clj" :git/sha "bd85a3de12d34a0622eb5b94d82c9e73b95412d1" :git/url "https://github.com/nextjournal/clerk"})
   (reset! config/!resource->url @config/!asset-map)
@@ -455,3 +457,4 @@
                       :bundle? true
                       :git/sha "d60f5417"
                       :git/url "https://github.com/nextjournal/clerk"}))
+

src/nextjournal/clerk/builder_ui.clj

@@ -22,18 +22,18 @@
 
 (defn checkmark-svg [& [{:keys [size] :or {size 18}}]]
   [:div.flex.justify-center {:class "w-[24px] h-[24px]"}
-   [:svg {:xmlns "http://www.w3.org/2000/svg", :fill "none", :viewbox "0 0 24 24", :stroke-width "1.5", :stroke "currentColor", :class "w-6 h-6"}
+   [:svg {:xmlns "http://www.w3.org/2000/svg", :fill "none", :viewBox "0 0 24 24", :stroke-width "1.5", :stroke "currentColor", :class "w-6 h-6"}
     [:path {:stroke-linecap "round", :stroke-linejoin "round", :d "M9 12.75L11.25 15 15 9.75M21 12a9 9 0 11-18 0 9 9 0 0118 0z"}]]])
 
 (defn error-svg [& [{:keys [size] :or {size 18}}]]
   [:div.flex.justify-center {:class "w-[24px] h-[24px]"}
    [:svg.text-red-400
-    {:xmlns "http://www.w3.org/2000/svg", :viewbox "0 0 20 20", :fill "currentColor"
+    {:xmlns "http://www.w3.org/2000/svg", :viewBox "0 0 20 20", :fill "currentColor"
      :style {:width size :height size}}
     [:path {:fill-rule "evenodd", :d "M8.485 2.495c.673-1.167 2.357-1.167 3.03 0l6.28 10.875c.673 1.167-.17 2.625-1.516 2.625H3.72c-1.347 0-2.189-1.458-1.515-2.625L8.485 2.495zM10 5a.75.75 0 01.75.75v3.5a.75.75 0 01-1.5 0v-3.5A.75.75 0 0110 5zm0 9a1 1 0 100-2 1 1 0 000 2z", :clip-rule "evenodd"}]]])
 
 (def publish-icon-svg
-  [:svg {:width "18", :height "18", :viewbox "0 0 18 18", :fill "none", :xmlns "http://www.w3.org/2000/svg"}
+  [:svg {:width "18", :height "18", :viewBox "0 0 18 18", :fill "none", :xmlns "http://www.w3.org/2000/svg"}
    [:path {:d "M9 17C12.7267 17 15.8583 14.4517 16.7473 11.0026M9 17C5.27327 17 2.14171 14.4517 1.25271 11.0026M9 17C11.2091 17 13 13.4183 13 9C13 4.58172 11.2091 1 9 1M9 17C6.79086 17 5 13.4183 5 9C5 4.58172 6.79086 1 9 1M9 1C11.9913 1 14.5991 2.64172 15.9716 5.07329M9 1C6.00872 1 3.40088 2.64172 2.02838 5.07329M15.9716 5.07329C14.102 6.68924 11.6651 7.66667 9 7.66667C6.33486 7.66667 3.89802 6.68924 2.02838 5.07329M15.9716 5.07329C16.6264 6.23327 17 7.573 17 9C17 9.69154 16.9123 10.3626 16.7473 11.0026M16.7473 11.0026C14.4519 12.2753 11.8106 13 9 13C6.18943 13 3.54811 12.2753 1.25271 11.0026M1.25271 11.0026C1.08775 10.3626 1 9.69154 1 9C1 7.573 1.37362 6.23327 2.02838 5.07329", :stroke "currentColor", :stroke-linecap "round", :stroke-linejoin "round"}]])
 
 ^{:nextjournal.clerk/visibility {:result :show}}
@@ -304,7 +304,7 @@
       (checkmark-svg)
       [:div.text-lg.ml-2.mb-0.font-medium "Your notebooks have been built."]]
      [:a.font-medium.rounded-full.text-sm.px-3.py-1.bg-greenish-20.flex.items-center.border-2.border-greenish.animate-border-pulse.hover:border-white.hover:animate-none
-      {:href link}
+      {:href link :data-ignore-anchor-click true}
       [:div publish-icon-svg]
       [:span.ml-2 "Open"]]]
     [:div.flex.items-center.px-4.lg:px-0

src/nextjournal/clerk/index.clj

@@ -15,7 +15,7 @@
                                       [:li.border-t.first:border-t-0.dark:border-gray-800.odd:bg-slate-50.dark:odd:bg-white
                                        {:class "dark:odd:bg-opacity-[0.03]"}
                                        [:a.pl-4.pr-4.py-2.flex.w-full.items-center.justify-between.hover:bg-indigo-50.dark:hover:bg-gray-700
-                                        {:href (clerk/doc-url path)}
+                                        {:href (clerk/doc-url (fs/strip-ext path))}
                                         [:span.text-sm.md:text-md.monospace.flex-auto.block.truncate path]
                                         [:svg.h-4.w-4.flex-shrink-0 {:xmlns "http://www.w3.org/2000/svg" :fill "none" :viewBox "0 0 24 24" :stroke "currentColor"}
                                          [:path {:stroke-linecap "round" :stroke-linejoin "round" :stroke-width "2" :d "M9 5l7 7-7 7"}]]]])))})