diff --git a/src/nextjournal/clerk.clj b/src/nextjournal/clerk.clj
index f56073408..f9c710171 100644
--- a/src/nextjournal/clerk.clj
+++ b/src/nextjournal/clerk.clj
@@ -222,13 +222,16 @@
   ([viewer-opts x] (v/html viewer-opts x)))
 
 (defn md
-  "Displays `x` with the markdown viewer.
+  "Displays `x` with the markdown viewer. Accepts strings or a structure as returned by [[nextjournal.markdown/parse]].
 
   Supports an optional first `viewer-opts` map arg with the following optional keys:
 
   * `:nextjournal.clerk/width`: set the width to `:full`, `:wide`, `:prose`
   * `:nextjournal.clerk/viewers`: a seq of viewers to use for presentation of this value and its children
-  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`"
+  * `:nextjournal.clerk/render-opts`: a map argument that will be passed as a secong arg to the viewers `:render-fn`.
+
+  See also [[nextjournal.clerk.viewer/markdown-viewer]]."
+
   ([x] (v/md x))
   ([viewer-opts x] (v/md viewer-opts x)))
 
@@ -553,7 +556,7 @@
 #_(with-cache (do (Thread/sleep 4200) 42))
 
 (defmacro defcached
-  "Like `clojure.core/def` but with Clerk's caching of the value."
+  "Like `clojure.core/def` but with Clerk's caching of the value. See also [[with-cache]]."
   [name expr]
   `(let [result# (-> ~(v/->edn expr) eval/eval-string :blob->result first val :nextjournal/value)]
      (def ~name result#)))
diff --git a/src/nextjournal/clerk/viewer.cljc b/src/nextjournal/clerk/viewer.cljc
index 6f964a676..8e68f5c24 100644
--- a/src/nextjournal/clerk/viewer.cljc
+++ b/src/nextjournal/clerk/viewer.cljc
@@ -472,7 +472,9 @@
                     %)
                  presented-result)))
 
-(defn get-default-viewers []
+(defn get-default-viewers
+  "Returns viewers from the global scope when set, defaults to [[default-viewers]] (see also [[!viewers]])."
+  []
   (:default @!viewers default-viewers))
 
 (defn datafy-scope [scope]
@@ -982,6 +984,7 @@
   {:name `vega-lite-viewer :render-fn 'nextjournal.clerk.render/render-vega-lite :transform-fn mark-presented})
 
 (def markdown-viewer
+  "A clerk viewer for rendering markdown. See also [[nextjournal.clerk/md]]."
   {:name `markdown-viewer
    :add-viewers markdown-viewers
    :transform-fn (fn [wrapped-value]