Overridable Markdown node Viewers

[zampino]

This set of changes (partially ¹) fits markdown rendering into the viewers API framework, in doing so we achieve:

• each markdown node (:heading, :paragraph, :monospace, etc) gets assigned an individual viewer and as such its appearance is completely customisable by the user via set-viewers! function. Check the markdown viewers notebook.
• markdown viewers might depend on other viewers. For instance the formula viewer now is implemented on top of the :latex viewer: changing the latter will affect all formulas inserted in markdown fragments. Check the mathjax example.

It is debatable if this is sufficient or if we want to move viewer selection on the clojure side as per latest trend.

• fix safari issues with Error: MathJax retry

Notes

¹: Markdown blocks are not described but passed to the client wrapped in with-viewer format. The client is still responsible for looking up the right viewer for each markdown node.

[zampino]

Trying to do viewer selection on the clojure side but it's not looking good. Starting with just a few nodes with a recursive describe step done via :transform-fn (which doesn't get passed describe opts) and unwrapping via value fn:

(def describe-children (map (comp value #(describe % {:viewers default-markdown-viewers}))))

(def default-markdown-viewers
  [{:name :nextjournal.markdown/formula
    :fetch-fn (fn [_ {:keys [text]}] text)
    :render-fn (quote v/katex-viewer)}

   {:name :nextjournal.markdown/text
    :fetch-fn (fn [_ {:keys [text]}] text)}

   {:name :nextjournal.markdown/paragraph
    :fetch-fn fetch-all
    :transform-fn (fn [{:nextjournal/keys [value]}]
                    (into [:p] describe-children (:content value)))}

   {:name :nextjournal.markdown/heading
    :fetch-fn fetch-all
    :transform-fn (fn [{:nextjournal/keys [value]}]
                    (let [{:keys [heading-level content]} value]
                      (into [(keyword (str \h heading-level))]
                            describe-children
                            content)))}])

(def default-viewers
  [{:name :nextjournal.markdown/doc
    :render-fn 'v/html
    :transform-fn (fn [wrapped-value]                       ;; FIXME: transform-fn doesn't take options
                    (-> wrapped-value
                        (update :nextjournal/value (fn [{:keys [content]}]
                                                     (into [:<>]
                                                           describe-children
                                                           content)))))
    :fetch-fn fetch-all}
...

and this looks kind of ok

(-> (nextjournal.markdown/parse "# Hello
some paragraph $\\phi$.
  ")
      nextjournal.clerk.view/md->viewer
      describe)
;; => 
{:path [],
 :nextjournal/value [:<> [:h1 "Hello"] [:p "some paragraph " "\\phi" "."]],
 :nextjournal/viewer {:name :nextjournal.markdown/doc, :render-fn #viewer-fnv/html}}

but I cannot easily get a grasp on the formula node :render-fn to have it use the latex viewer. We'd also have to check that this approach is still open for user-facing overrides.

[zampino]

or if we want to move viewer selection on the clojure side

This is actually relying on "client-side viewer registration" which is being dropped with https://github.com/nextjournal/clerk/compare/drop-eval-viewer. The current approach won't make sense any longer, so we'll need to go for an actual server-side description.

[zampino]

Superseded by #122.