Suppport local Files in Markdown Images (#419)

With these changes, image sources in markdown comments are transformed according to:

* `serve!`: the file path is served as-is by clerk webserver
* `(build! {:bundle true})` images are inlined as base64 encoded data
* `(build! {:bundle false})`: images are content addressed and stored in the `_data` folder

In addition, we now allow `clerk/image` to be called against local paths.

Closes #223.

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

Author: zampino

.gitattributes

@@ -1,2 +1,3 @@
 ;; always force unix line endings to make hashing consistent
-* text eol=lf
+* text eol=lf
+*.png binary

notebooks/viewers/image.clj

@@ -1,8 +1,10 @@
 ;; # 🏞 Image Viewer
 (ns image
-  (:require [nextjournal.clerk :as clerk])
-  (:import (java.net URL)
-           (javax.imageio ImageIO)))
+  (:require [babashka.fs :as fs]
+            [nextjournal.clerk :as clerk])
+  (:import (javax.imageio ImageIO)
+           (java.awt.image BufferedImage)
+           (java.net URL)))
 
 ;; Clerk now comes with a default viewer for `java.awt.image.BufferedImage`. It looks at the dimensions of the image, and tries to do the right thing. For an image larger than 900px wide with an aspect ratio larger 2, it uses full width.
 (ImageIO/read (URL. "https://images.unsplash.com/photo-1532879311112-62b7188d28ce?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8"))
@@ -13,9 +15,20 @@
 (clerk/image "https://images.freeimages.com/images/large-previews/773/koldalen-4-1384902.jpg")
 
 ;; Smaller images are centered and shown using their intrinsic dimensions. Here, we're using `clerk/figure`:
-
 (clerk/image "https://nextjournal.com/data/QmeyvaR3Q5XSwe14ZS6D5WBQGg1zaBaeG3SeyyuUURE2pq?filename=thermos.gif&content-type=image/gif")
 
 ;; Layout options are also available. For example, `{::clerk/width :full}` renders the image in full width.
-
 (clerk/image {::clerk/width :full} "https://images.freeimages.com/images/large-previews/773/koldalen-4-1384902.jpg")
+
+;; We also support local files for `clerk/image`:
+(clerk/image "trees.png")
+
+;; ## Markdown Notation
+
+;; Given a local file named `trees.png` we can use the markdown image syntax `![alt text](trees.png)` to get:
+;;
+;; ![Drawing of trees in black and white](trees.png)
+;;
+;; This also works for https urls, of course.
+;;
+;; Images occuring inside a paragraph are placed inline like this ![Clerk CI Status](https://github.com/nextjournal/clerk/actions/workflows/main.yml/badge.svg) badge.

src/nextjournal/clerk/viewer.cljc

@@ -23,7 +23,7 @@
                    (java.lang Throwable)
                    (java.awt.image BufferedImage)
                    (java.util Base64)
-                   (java.net URL)
+                   (java.net URI URL)
                    (java.nio.file Files StandardOpenOption)
                    (javax.imageio ImageIO))))
 
@@ -316,11 +316,11 @@
     (-> (with-viewer {:name `html-viewer- :render-fn 'identity} wrapped-value)
         mark-presented
         (update :nextjournal/value
-                (fn [{:as node :keys [text content]}]
+                (fn [{:as node :keys [text content] ::keys [doc]}]
                   (into (cond-> markup (fn? markup) (apply [node]))
                         (cond text [text]
-                              content (mapv #(-> (with-md-viewer %)
-                                                 (assoc :nextjournal/viewers viewers)
+                              content (mapv #(-> (ensure-wrapped-with-viewers viewers (assoc % ::doc doc))
+                                                 (with-md-viewer)
                                                  (apply-viewers)
                                                  (as-> w
                                                      (if (= `html-viewer- (:name (->viewer w)))
@@ -397,14 +397,13 @@
     result))
 
 #?(:clj
-   (defn base64-encode-value [{:as result :nextjournal/keys [content-type]}]
-     (update result :nextjournal/value (fn [data] (str "data:" content-type ";base64,"
-                                                       (.encodeToString (Base64/getEncoder) data))))))
+   (defn data-uri-base64-encode [x content-type]
+     (str "data:" content-type ";base64," (.encodeToString (Base64/getEncoder) x))))
 
 #?(:clj
    (defn store+get-cas-url! [{:keys [out-path ext]} content]
-     (assert out-path) (assert ext)
-     (let [cas-url (str "_data/" (analyzer/sha2-base58 content) "." ext)
+     (assert out-path)
+     (let [cas-url (str "_data/" (analyzer/sha2-base58 content) (when ext ".") ext)
            cas-path (fs/path out-path cas-url)]
        (fs/create-dirs (fs/parent cas-path))
        (when-not (fs/exists? cas-path)
@@ -433,10 +432,10 @@
 
 #?(:clj
    (defn process-blobs [{:as doc+blob-opts :keys [blob-mode blob-id]} presented-result]
-     (w/postwalk #(if (get % :nextjournal/content-type)
+     (w/postwalk #(if-some [content-type (get % :nextjournal/content-type)]
                     (case blob-mode
                       :lazy-load (assoc % :nextjournal/value {:blob-id blob-id :path (:path %)})
-                      :inline (base64-encode-value %)
+                      :inline (update % :nextjournal/value data-uri-base64-encode content-type)
                       :file (maybe-store-result-as-file doc+blob-opts %))
                     %)
                  presented-result)))
@@ -463,7 +462,7 @@
 
 (declare result-viewer)
 
-(defn transform-result [{:as _cell :keys [doc result form]}]
+(defn transform-result [{:as _cell :keys [result form] ::keys [doc]}]
   (let [{:keys [auto-expand-results? inline-results? bundle?]} doc
         {:nextjournal/keys [value blob-id viewers]} result
         blob-mode (cond
@@ -507,18 +506,54 @@
 #_(->display {:result {:nextjournal.clerk/visibility {:code :fold :result :show}}})
 #_(->display {:result {:nextjournal.clerk/visibility {:code :fold :result :hide}}})
 
-(defn process-sidenotes [{:as doc :keys [footnotes]} cell-doc]
+(defn process-sidenotes [cell-doc {:keys [footnotes]}]
   (if (seq footnotes)
     (md.parser/insert-sidenote-containers (assoc cell-doc :footnotes footnotes))
     cell-doc))
 
+(defn process-image-source [src {:as doc :keys [file bundle?]}]
+  #?(:cljs src
+     :clj  (cond
+             (not (fs/exists? src)) src
+             (false? bundle?) (str (relative-root-prefix-from (map-index doc file))
+                                   (store+get-cas-url! (assoc doc :ext (fs/extension src))
+                                                       (fs/read-all-bytes src)))
+             bundle? (data-uri-base64-encode (fs/read-all-bytes src) (Files/probeContentType (fs/path src)))
+             :else (str "_fs/" src))))
+
+#?(:clj
+   (defn read-image [image-or-url]
+     (ImageIO/read
+      (if (string? image-or-url)
+        (URL. (cond->> image-or-url (not (.getScheme (URI. image-or-url))) (str "file:")))
+        image-or-url))))
+
+#?(:clj
+   (defn image-width [image]
+     (let [w (.getWidth image) h (.getHeight image) r (float (/ w h))]
+       (if (and (< 2 r) (< 900 w)) :full :wide))))
+
+(defn md-image->viewer [doc {:keys [attrs]}]
+  (with-viewer `html-viewer
+    #?(:clj {:nextjournal.clerk/width (try (image-width (read-image (:src attrs)))
+                                           (catch Throwable _ :prose))})
+    [:div.flex.flex-col.items-center.not-prose.mb-4
+     [:img (update attrs :src process-image-source doc)]]))
+
 (defn with-block-viewer [doc {:as cell :keys [type]}]
   (case type
-    :markdown [(with-viewer `markdown-viewer (process-sidenotes doc (:doc cell)))]
+    :markdown (let [{:keys [content]} (:doc cell)]
+                (mapcat (fn [fragment]
+                          (if (= :image (:type (first fragment)))
+                            (map (partial md-image->viewer doc) fragment)
+                            [(with-viewer `markdown-viewer (process-sidenotes {:type :doc
+                                                                               :content (vec fragment)
+                                                                               ::doc doc} doc))]))
+                        (partition-by (comp #{:image} :type) content)))
+
     :code (let [cell (update cell :result apply-viewer-unwrapping-var-from-def)
                 {:as display-opts :keys [code? result?]} (->display cell)
                 eval? (-> cell :result :nextjournal/value (get-safe :nextjournal/value) viewer-eval?)]
-            ;; TODO: use vars instead of names
             (cond-> []
               code?
               (conj (with-viewer `code-block-viewer {:nextjournal.clerk/opts (select-keys cell [:loc])}
@@ -528,7 +563,7 @@
               (conj (with-viewer (if result?
                                    (:name result-viewer)
                                    (assoc result-viewer :render-fn '(fn [_] [:<>])))
-                      (assoc cell :doc doc)))))))
+                      (assoc cell ::doc doc)))))))
 
 #_(nextjournal.clerk.view/doc->viewer @nextjournal.clerk.webserver/!doc)
 
@@ -614,13 +649,14 @@
 (def markdown-viewers
   [{:name :nextjournal.markdown/doc
     :transform-fn (into-markup [:div.markdown-viewer])}
-
-   ;; blocks
    {:name :nextjournal.markdown/heading
     :transform-fn (into-markup
                    (fn [{:keys [attrs heading-level]}]
                      [(str "h" heading-level) attrs]))}
-   {:name :nextjournal.markdown/image :transform-fn #(with-viewer `html-viewer [:img.inline (-> % ->value :attrs)])}
+   {:name :nextjournal.markdown/image
+    :transform-fn (fn [{node :nextjournal/value}]
+                    (with-viewer `html-viewer
+                      [:img.inline (-> node :attrs (update :src process-image-source (::doc node)))]))}
    {:name :nextjournal.markdown/blockquote :transform-fn (into-markup [:blockquote])}
    {:name :nextjournal.markdown/paragraph :transform-fn (into-markup [:p])}
    {:name :nextjournal.markdown/plain :transform-fn (into-markup [:<>])}
@@ -749,18 +785,15 @@
 (def image-viewer
   {#?@(:clj [:pred #(instance? BufferedImage %)
              :transform-fn (fn [{image :nextjournal/value}]
-                             (let [w (.getWidth image)
-                                   h (.getHeight image)
-                                   r (float (/ w h))]
-                               (-> {:nextjournal/value (.. (PngEncoder.)
-                                                           (withBufferedImage image)
-                                                           (withCompressionLevel 1)
-                                                           (toBytes))
-                                    :nextjournal/content-type "image/png"
-                                    :nextjournal/width (if (and (< 2 r) (< 900 w)) :full :wide)}
-                                   mark-presented)))])
+                             (-> {:nextjournal/value (.. (PngEncoder.)
+                                                         (withBufferedImage image)
+                                                         (withCompressionLevel 1)
+                                                         (toBytes))
+                                  :nextjournal/content-type "image/png"
+                                  :nextjournal/width (image-width image)}
+                                 mark-presented))])
    :render-fn '(fn [blob-or-url] [:div.flex.flex-col.items-center.not-prose
-                                  [:img {:src #?(:clj (nextjournal.clerk.render/url-for blob-or-url)
+                                  [:img {:src #?(:clj  (nextjournal.clerk.render/url-for blob-or-url)
                                                  :cljs blob-or-url)}]])})
 
 (def ideref-viewer
@@ -1527,8 +1560,8 @@
 (defn image
   ([image-or-url] (image {} image-or-url))
   ([viewer-opts image-or-url]
-   (with-viewer image-viewer viewer-opts #?(:clj (ImageIO/read (if (string? image-or-url) (URL. image-or-url) image-or-url))
-                                            :cljs image-or-url))))
+   (with-viewer image-viewer viewer-opts
+     #?(:cljs image-or-url :clj (read-image image-or-url)))))
 
 (defn caption [text content]
   (col

src/nextjournal/clerk/webserver.clj

@@ -7,7 +7,8 @@
             [editscript.core :as editscript]
             [nextjournal.clerk.view :as view]
             [nextjournal.clerk.viewer :as v]
-            [org.httpkit.server :as httpkit]))
+            [org.httpkit.server :as httpkit])
+  (:import (java.nio.file Files)))
 
 (defn help-hiccup []
   [:p "Call " [:span.code "nextjournal.clerk/show!"] " from your REPL"
@@ -90,20 +91,14 @@
   {:blob-id (str/replace uri "/_blob/" "")
    :fetch-opts (get-fetch-opts query-string)})
 
-(defn serve-file [path {:as req :keys [uri]}]
-  (let [file-or-dir (str path uri)
-        file (when (fs/exists? file-or-dir)
-               (cond-> file-or-dir
-                 (fs/directory? file-or-dir) (fs/file "index.html")))
-        extension (fs/extension file)]
+(defn serve-file [uri path]
+  (let [file (when (fs/exists? path)
+               (cond-> path
+                 (fs/directory? path) (fs/file "index.html")))]
     (if (fs/exists? file)
       {:status 200
-       :headers (cond-> {"Content-Type" ({"css" "text/css"
-                                          "html" "text/html"
-                                          "png" "image/png"
-                                          "jpg" "image/jpeg"
-                                          "js" "application/javascript"} extension "text/html")}
-                  (and (= "js" extension) (fs/exists? (str file ".map"))) (assoc "SourceMap" (str uri ".map")))
+       :headers (cond-> {"Content-Type" (Files/probeContentType (fs/path file))}
+                  (and (= "js" (fs/extension file)) (fs/exists? (str file ".map"))) (assoc "SourceMap" (str uri ".map")))
        :body (fs/read-all-bytes file)}
       {:status 404})))
 
@@ -152,7 +147,8 @@
     (try
       (case (get (re-matches #"/([^/]*).*" uri) 1)
         "_blob" (serve-blob @!doc (extract-blob-opts req))
-        ("build" "js" "css") (serve-file "public" req)
+        ("build" "js" "css") (serve-file uri (str "public" uri))
+        ("_fs") (serve-file uri (str/replace uri "/_fs/" ""))
         "_ws" {:status 200 :body "upgrading..."}
         {:status 200
          :headers {"Content-Type" "text/html"}

test/nextjournal/clerk/viewer_test.clj

@@ -1,5 +1,6 @@
 (ns nextjournal.clerk.viewer-test
-  (:require [clojure.string :as str]
+  (:require [babashka.fs :as fs]
+            [clojure.string :as str]
             [clojure.test :refer [deftest is testing]]
             [clojure.walk :as w]
             [matcher-combinators.test :refer [match?]]
@@ -202,6 +203,12 @@
                  v/->viewer
                  :closing-paren))))))
 
+(defn tree-re-find [data re]
+  (->> data
+       (tree-seq coll? seq)
+       (filter string?)
+       (filter (partial re-find re))))
+
 (deftest doc->viewer
   (testing "extraction of synced vars"
     (is (not-empty (-> (view/doc->viewer (eval/eval-string "(ns nextjournal.clerk.test.sync-vars (:require [nextjournal.clerk :as clerk]))
@@ -217,12 +224,20 @@
          (view/doc->viewer (eval/eval-string "(ns nextjournal.clerk.test.sync-vars (:require [nextjournal.clerk :as clerk]))
                                      ^::clerk/sync (def sync-me (atom {:a (fn [x] x)}))")))))
 
+  (testing "Local images are served as blobs in show mode"
+    (let [test-doc (eval/eval-string ";; Some inline image ![alt](trees.png) here.")]
+      (is (not-empty (tree-re-find (view/doc->viewer test-doc) #"_fs/trees.png")))))
+
+  (testing "Local images are inlined in bundled static builds"
+    (let [test-doc (eval/eval-string ";; Some inline image ![alt](trees.png) here.")]
+      (is (not-empty (tree-re-find (view/doc->viewer {:bundle? true} test-doc) #"data:image/png;base64")))))
+
+  (testing "Local images are content addressed for unbundled static builds"
+    (let [test-doc (eval/eval-string ";; Some inline image ![alt](trees.png) here.")]
+      (is (not-empty (tree-re-find (view/doc->viewer {:bundle? false :out-path (str (fs/temp-dir))} test-doc) #"_data/.+\.png")))))
+
   (testing "Doc options are propagated to blob processing"
-    (let [test-doc (eval/eval-string "(java.awt.image.BufferedImage. 20 20 1)")
-          tree-re-find (fn [data re] (->> data
-                                          (tree-seq coll? seq)
-                                          (filter string?)
-                                          (filter (partial re-find re))))]
+    (let [test-doc (eval/eval-string "(java.awt.image.BufferedImage. 20 20 1)")]
       (is (not-empty (tree-re-find (view/doc->viewer {:inline-results? true
                                                       :bundle? true
                                                       :out-path builder/default-out-path} test-doc)