Naming and docs

notebooks/meta_toc.clj

@@ -154,4 +154,4 @@
   ;; Test actual cross-doc toc
   (viewer/reset-viewers! :default (viewer/add-viewers [(notebook-viewer {:paths paths})]))
   (reset! viewer/!viewers {})
-  (clerk/build! {:xhr? true :paths paths}))
+  (clerk/build! {:client-side-routing? true :paths paths}))

src/nextjournal/clerk.clj

@@ -417,7 +417,7 @@
 
 (defn ^:private normalize-opts [opts]
   (set/rename-keys opts #_(into {} (map (juxt identity #(keyword (str (name %) "?")))) [:bundle :browse :dashboard])
-                   {:bundle :bundle?, :browse :browse?, :dashboard :dashboard? :compile-css :compile-css? :ssr :ssr? :exclude-js :exclude-js?}))
+                   {:bundle :bundle?, :browse :browse?, :dashboard :dashboard? :compile-css :compile-css? :ssr :ssr? :exclude-js :exclude-js? :client-side-routing :client-side-routing?}))
 
 (defn ^:private started-via-bb-cli? [opts]
   (contains? (meta opts) :org.babashka/cli))
@@ -491,12 +491,13 @@
   Passing at least one of the above is required. When both `:paths`
   and `:paths-fn` are given, `:paths` takes precendence.
 
-  - `:bundle`      - if true results in a single self-contained html file including inlined images
-  - `:compile-css` - if true compiles css file containing only the used classes
-  - `:ssr`         - if true runs react server-side-rendering and includes the generated markup in the html
-  - `:browse`      - if true will open browser with the built file on success
-  - `:dashboard`   - if true will start a server and show a rich build report in the browser (use with `:bundle` to open browser)
-  - `:out-path`  - a relative path to a folder to contain the static pages (defaults to `\"public/build\"`)
+  - `:bundle`              - if true results in a single self-contained html file including inlined images
+  - `:client-side-routing` - if true navigation across documents is handled by the client (the `:bundle` option must not be true for this to have effect)
+  - `:compile-css`         - if true compiles css file containing only the used classes
+  - `:ssr`                 - if true runs react server-side-rendering and includes the generated markup in the html
+  - `:browse`              - if true will open browser with the built file on success
+  - `:dashboard`           - if true will start a server and show a rich build report in the browser (use with `:bundle` to open browser)
+  - `:out-path`            - a relative path to a folder to contain the static pages (defaults to `\"public/build\"`)
   - `:git/sha`, `:git/url` - when both present, each page displays a link to `(str url \"blob\" sha path-to-notebook)`
   "
   {:org.babashka/cli {:spec {:paths {:desc "Paths to notebooks toc include in the build, supports glob patterns."
@@ -505,6 +506,7 @@
                                         :coerce :symbol}
                              :index {:desc "Override the name of the index file (default `index.clj|md`), will be added to paths."}
                              :bundle {:desc "Flag to build a self-contained html file inlcuding inlined images"}
+                             :client-side-routing {:desc "Flag to tell the client to handle navigation across document links. Has an effect only when the `:bundle` flag is not used."}
                              :browse {:desc "Opens the browser on boot when set."}
                              :dashboard {:desc "Flag to serve a dashboard with the build progress."}
                              :out-path {:desc "Path to an build output folder, defaults to \"public/build\"."}

src/nextjournal/clerk/builder.clj

@@ -180,11 +180,11 @@
 
 (defn cleanup [build-opts]
   (select-keys build-opts
-               [:bundle? :xhr? :path->doc :current-path :resource->url :exclude-js? :index :html]))
+               [:bundle? :client-side-routing? :path->doc :current-path :resource->url :exclude-js? :index :html]))
 
 (defn write-static-app!
   [opts docs]
-  (let [{:keys [bundle? xhr? out-path browse? ssr?]} opts
+  (let [{:keys [bundle? client-side-routing? out-path browse? ssr?]} opts
         index-html (str out-path fs/file-separator "index.html")
         {:as static-app-opts :keys [path->doc]} (build-static-app-opts opts docs)]
     (when-not (contains? (set (keys path->doc)) "")
@@ -196,7 +196,7 @@
       (doseq [[path doc] path->doc]
         (let [out-html (fs/file out-path path "index.html")]
           (fs/create-dirs (fs/parent out-html))
-          (when xhr?
+          (when client-side-routing?
             (spit (str (fs/path out-path (str (or (not-empty path) "index") ".edn")))
                   (viewer/->edn doc)))
           (spit out-html (view/->html (-> static-app-opts

src/nextjournal/clerk/render.cljs

@@ -772,7 +772,7 @@
             (assoc state :listeners
                    (cond (and (static-app? state) (:bundle? state))
                          [(gevents/listen js/window gevents/EventType.HASHCHANGE (partial handle-hashchange state) false)]
-                         (and (static-app? state) (:xhr? state))
+                         (and (static-app? state) (:client-side-routing? state))
                          [(gevents/listen js/document gevents/EventType.CLICK click->xhr-request false)]
                          (not (static-app? state))
                          [(gevents/listen js/document gevents/EventType.CLICK handle-anchor-click false)