Home page & index improvements (#458)

This improves the homepage including dark mode support. We also unify the index and make it usable in interactive mode so it's no longer needed to perform a `build!` to see it.

Add a header to the interactive mode that allows to navigate to both the index and home and allow to customize it.

Co-authored-by: Martin Kavalar <martin@nextjournal.com>
Co-authored-by: Andrea Amantini <lo.zampino@gmail.com>

Author: 3 people

resources/stylesheets/viewer.css

@@ -137,7 +137,7 @@
 }
 @media (min-width: 960px){
     .notebook-viewer .code-viewer .cm-content {
-        @apply py-4 pl-12;
+        @apply pb-2 pl-12;
     }
     .notebook-viewer .code-listing {
         width: 48rem !important;
@@ -300,8 +300,6 @@
 /* Notebook Spacing */
 /* --------------------------------------------------------------- */
 
-.notebook-viewer { @apply py-16; }
-#clerk-static-app .notebook-viewer { @apply pt-[0.8rem] pb-16; }
 .markdown-viewer *:first-child:not(.code-viewer):not(li):not(h2):not(.sidenote) { @apply mt-0; }
 /*.viewer + .viewer { @apply mt-6; }*/
 .viewer + .result-viewer { @apply mt-0; }

src/nextjournal/clerk.clj

@@ -11,7 +11,6 @@
             [nextjournal.clerk.config :as config]
             [nextjournal.clerk.eval :as eval]
             [nextjournal.clerk.parser :as parser]
-            [nextjournal.clerk.view :as view]
             [nextjournal.clerk.viewer :as v]
             [nextjournal.clerk.webserver :as webserver]))
 
@@ -393,13 +392,6 @@
     `(nextjournal.clerk/with-viewer v/examples-viewer
        (mapv (fn [form# val#] {:form form# :val val#}) ~(mapv (fn [x#] `'~x#) body) ~(vec body)))))
 
-(defn file->viewer
-  "Evaluates the given `file` and returns it's viewer representation."
-  ([file] (file->viewer {:inline-results? true} file))
-  ([opts file] (view/doc->viewer opts (eval/eval-file file))))
-
-#_(file->viewer "notebooks/rule_30.clj")
-
 (defn halt-watcher!
   "Halts the filesystem watcher when active."
   []

src/nextjournal/clerk/builder.clj

@@ -2,6 +2,7 @@
   "Clerk's Static App Builder."
   (:require [babashka.fs :as fs]
             [babashka.process :refer [sh]]
+            [clojure.edn :as edn]
             [clojure.java.browse :as browse]
             [clojure.java.io :as io]
             [clojure.string :as str]
@@ -12,7 +13,8 @@
             [nextjournal.clerk.view :as view]
             [nextjournal.clerk.viewer :as viewer]
             [nextjournal.clerk.webserver :as webserver]
-            [nextjournal.clerk.config :as config]))
+            [nextjournal.clerk.config :as config])
+  (:import (java.net URL)))
 
 (def clerk-docs
   (into ["CHANGELOG.md"
@@ -124,9 +126,11 @@
     (throw (ex-info "nothing to build" (merge {:expanded-paths expanded-paths} (select-keys build-opts [:paths :paths-fn :index]))))
     expanded-paths))
 
-(defn ^:private maybe-add-index [{:as build-opts :keys [paths paths-fn index]} resolved-paths]
-  (when (and index (or (not (string? index)) (not (fs/exists? index))))
-    (throw (ex-info "`:index` must be string and point to existing file" {:index index})))
+(defn ^:private maybe-add-index [{:as opts :keys [index]} resolved-paths]
+  (when (contains? opts :index)
+    (or (instance? URL index)
+        (and (string? index) (fs/exists? index))
+        (throw (ex-info "`:index` must be either an instance of java.net.URL or a string and point to an existing file" {:index index}))))
   (cond-> resolved-paths
     (and index (not (contains? (set resolved-paths) index)))
     (conj index)))
@@ -185,22 +189,30 @@
            (-> opts'
                (update :resource->url #(merge {} %2 %1) @config/!resource->url)
                (cond-> #_opts'
-                 expand-paths? (dissoc :expand-paths?)
-                 (and (not index) (= 1 (count expanded-paths))) (assoc :index (first expanded-paths)))))))
+                 expand-paths?
+                 (dissoc :expand-paths?)
+                 (and (not index) (= 1 (count expanded-paths)))
+                 (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)))))))))
 
 #_(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))
-                   :file))
+                   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 :file :viewer)) docs)]
+  (let [path->doc (into {} (map (juxt (comp str :file) :viewer)) docs)]
     (assoc opts
            :bundle? bundle?
            :path->doc path->doc
@@ -230,23 +242,23 @@
   [opts docs]
   (let [{:as opts :keys [bundle? out-path browse? ssr?]} (process-build-opts opts)
         index-html (str out-path fs/file-separator "index.html")
-        {:as static-app-opts :keys [path->url path->doc]} (build-static-app-opts opts docs)]
+        {: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})))
     (when-not (fs/exists? (fs/parent index-html))
       (fs/create-dirs (fs/parent index-html)))
     (if bundle?
       (spit index-html (view/->static-app static-app-opts))
-      (do (when-not (contains? (-> path->url vals set) "") ;; no user-defined index page
-            (spit index-html (view/->static-app (dissoc static-app-opts :path->doc))))
-          (doseq [[path doc] path->doc]
-            (let [out-html (str out-path fs/file-separator (->> path (viewer/map-index opts) ->html-extension))]
-              (fs/create-dirs (fs/parent out-html))
-              (spit out-html (view/->static-app (cond-> (assoc static-app-opts :path->doc (hash-map path doc) :current-path path)
-                                                  ssr? ssr!)))))))
+      (doseq [[path doc] path->doc]
+        (let [out-html (str out-path fs/file-separator (->> path (viewer/map-index opts) ->html-extension))]
+          (fs/create-dirs (fs/parent out-html))
+          (spit out-html (view/->static-app (cond-> (assoc static-app-opts :path->doc (hash-map path doc) :current-path path)
+                                              ssr? ssr!))))))
     (when browse?
       (browse/browse-url (-> 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)}))
+     :build-href (if (and @webserver/!server (= out-path default-out-path)) "/build/" index-html)}))
 
 
 (defn compile-css!
@@ -287,12 +299,29 @@
 (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)]
+   (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)))))))
 
+(defn read-opts-from-deps-edn! []
+  (if (fs/exists? "deps.edn")
+    (let [deps-edn (edn/read-string (slurp "deps.edn"))]
+      (if-some [clerk-alias (get-in deps-edn [:aliases :nextjournal/clerk])]
+        (get clerk-alias :exec-args
+             {:error "No `:exec-args` found in `:nextjournal/clerk` alias."})
+        {:error "No `:nextjournal/clerk` alias found in `deps.edn`."}))
+    {:error "No `deps.edn` found in project."}))
+
+(def ^:dynamic ^:private *build-opts* nil)
+(defn index-paths []
+  (let [{:as opts :keys [index error]} (or *build-opts* (read-opts-from-deps-edn!))]
+    (if error opts {:paths (remove #{index "index.clj"} (expand-paths opts))})))
+
+#_(index-paths)
+#_(nextjournal.clerk/show! 'nextjournal.clerk.index)
+
 (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]}
         (try (process-build-opts (assoc opts :expand-paths? true))
@@ -324,9 +353,11 @@
                       (report-fn {:stage :building :doc doc :idx idx})
                       (let [{result :result duration :time-ms} (eval/time-ms
                                                                 (try
-                                                                  (let [doc (binding [viewer/doc-url (partial doc-url opts state file)]
-                                                                              (eval/eval-analyzed-doc doc))]
-                                                                    (assoc doc :viewer (view/doc->viewer (assoc opts :inline-results? true) doc)))
+                                                                  (binding [*build-opts* opts
+                                                                            viewer/doc-url (partial doc-url opts state file)]
+                                                                    (let [doc (eval/eval-analyzed-doc doc)]
+                                                                      (assoc doc :viewer (view/doc->viewer (assoc opts :static-build? true
+                                                                                                                  :nav-path (str file)) doc))))
                                                                   (catch Exception e
                                                                     {:error e})))]
                         (report-fn (merge {:stage :built :duration duration :idx idx}
@@ -369,3 +400,9 @@
                       :resource->url {"/js/viewer.js" "/viewer.js"}
                       :paths ["notebooks/cherry.clj"]
                       :out-path "build"})
+#_(build-static-app! {:paths ["CHANGELOG.md"
+                              "notebooks/markdown.md"
+                              "notebooks/viewers/image.clj"
+                              "notebooks/viewers/html.cj"]
+                      :git/sha "d60f5417"
+                      :git/url "https://github.com/nextjournal/clerk"})

src/nextjournal/clerk/home.clj

@@ -19,19 +19,24 @@
 ^{::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
+  [:div.md:flex.md:justify-between.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.rounded-lg.border-2.border-amber-100.bg-amber-50.dark:border-slate-600.dark:bg-slate-800.dark:text-slate-100.px-8.py-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!"]
+    "Call "
+    [:span.font-mono.text-sm.bg-white.bg-amber-100.border.border-amber-300.relative.dark:bg-slate-900.dark:border-slate-600.rounded.font-bold
+     {:class "px-[4px] py-[1px] -top-[1px] mx-[2px]"}
+     "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.rounded-lg.border-2.border-indigo-100.bg-indigo-50.dark:border-slate-600.dark:bg-slate-800.dark:text-slate-100.px-8.py-4.mt-6.text-center.font-sans
+   [:div.font-medium.md:flex.items-center.justify-center
+    [:span.text-xl.relative {:class "top-[2px] mr-2"} "📖"]
+    [:span "New to Clerk? Learn all about it in " [:a {:href "https://book.clerk.vision"} [:span.block.md:inline "The Book of Clerk."]]]]
    #_
    [:div.mt-2.text-sm
     "Here are some handy links:"

src/nextjournal/clerk/index.clj

@@ -0,0 +1,58 @@
+(ns nextjournal.clerk.index
+  {:nextjournal.clerk/visibility {:code :hide :result :hide}
+   :nextjournal.clerk/no-cache true}
+  (:require [nextjournal.clerk :as clerk]
+            [nextjournal.clerk.viewer :as v]
+            [nextjournal.clerk.builder :as builder]))
+
+(def !paths (delay (builder/index-paths)))
+
+(def index-item-viewer
+  {:pred string?
+   :transform-fn (clerk/update-val (fn [path]
+                                     (clerk/html
+                                      [: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)}
+                                        [: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"}]]]])))})
+
+(def index-viewer
+  {:render-fn '(fn [xs opts]
+                 [:div.not-prose
+                  [:h1.mb-4 "Clerk"]
+                  (into [:ul.border.dark:border-slate-800.rounded-md.overflow-hidden]
+                        (nextjournal.clerk.render/inspect-children opts)
+                        xs)])
+   :transform-fn (fn [wrapped-value]
+                   (update wrapped-value :nextjournal/viewers v/add-viewers [index-item-viewer]))})
+
+{::clerk/visibility {:result :show}}
+(let [{:keys [paths error]} @!paths]
+  (cond
+    error (clerk/md error)
+    paths (clerk/with-viewer index-viewer paths)))
+
+#_[:div.bg-gray-100.dark:bg-gray-900.flex.justify-center.overflow-y-auto.w-screen.h-screen.p-4.md:p-0
+   {:ref ref-fn}
+   [:div.fixed.top-2.left-2.md:left-auto.md:right-2.z-10
+    [render/dark-mode-toggle !state]]
+   [:div.md:my-12.w-full.md:max-w-lg
+    [:div.bg-white.dark:bg-gray-800.shadow-lg.rounded-lg.border.dark:border-gray-800.dark:text-white
+     [:div.px-4.md:px-8.py-3
+      [:h1.text-xl "Clerk"]]
+     (into [:ul]
+           (map (fn [path]
+                  [:li.border-t.dark:border-gray-900
+                   [:a.pl-4.md:pl-8.pr-4.py-2.flex.w-full.items-center.justify-between.hover:bg-indigo-50.dark:hover:bg-gray-700
+                    {:href (doc-url view-data 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"}]]]]))
+           (sort paths))]
+    [:div.my-4.md:mb-0.text-xs.text-gray-400.sans-serif.px-4.md:px-8
+     [:a.hover:text-indigo-600.dark:hover:text-white
+      {:href "https://github.com/nextjournal/clerk"}
+      "Generated with Clerk."]]]]