nextjournal markdown

A cross-platform clojure library for Markdown parsing and transformation.

---

🚧 ALPHA status, subject to frequent change. 🚧

For a richer reading experience and read this readme as a clerk notebook.

Features 🦶

• Focus on data: parsing yields an AST (à la Pandoc) of nested data representing a structured document.

• Cross Platform: clojurescript native with bindings to the JVM using Graal's Polyglot Engine.

• Configurable Hiccup conversion: Uses hiccup for custom markdown representation.

Flavor 👅

By building on top of markdown-it, we adhere to CommonMark Spec and also comply with extensions from Github flavoured Markdown. Additionally, we parse $\LaTeX$ formulas (with $ for inline latex or $$ for equation display).

Usage 🔩

(ns hello-markdown
  (:require [nextjournal.markdown :as md]
            [nextjournal.markdown.transform :as md.transform]))

Parsing markdown into an AST:

(def data (md/parse "### 👋🏻 Hello Markdown
* this _looks_

* something ~~unusual~~ **familiar**
---
"))
;; =>
;; {:type :doc
;;  :toc {:type :toc :children [...]}
;;  :title "👋🏻 Hello Markdown"
;;  :content [{:type :heading
;;             :content [{:type :text :text "👋🏻 Hello Markdown"}] :heading-level 3}
;;            {:type :bullet-list
;;             :content [{:type :list-item
;;                        :content [{:type :paragraph
;;                                   :content [{:type :text :text "this "}
;;                                             {:type :em :content [{:type :text :text "looks"}]}]}]}
;;                       {:type :list-item
;;                        :content [{:type :paragraph
;;                                   :content [{:type :text :text "something "}
;;                                             {:type :strikethrough, :content [{:type :text :text "unusual"}]}
;;                                             {:type :text :text " "}
;;                                             {:type :strong, :content [{:type :text :text "familiar"}]}]}]}]}
;;            {:type :ruler}]}

and transform that AST into hiccup syntax.

(md.transform/->hiccup data)
;; =>
;; [:div
;;  [:h3 {:id "%F0%9F%91%8B%F0%9F%8F%BB%20Hello%20Markdown"} "👋🏻 Hello Markdown"]
;;  [:ul [:li [:p "this " [:em "looks"]]] [:li [:p "something " [:s "unusual"] " " [:strong "familiar"]]]]
;;  [:hr]]

We've built hiccup transformation in for convenience, but the same approach can be used to target more formats.

This library is one of the building blocks of Clerk where it is used for rendering literate fragments.

^{:nextjournal.clerk/viewer :markdown}
data
;; If you don't see "👋 Hello Markdown" below,
;; consider loading this README as a notebook!
;; https://nextjournal.github.io/markdown/#/README.md

The transformation of markdown node types can be specified like this:

^{:nextjournal.clerk/viewer :html}
(md.transform/->hiccup
 (assoc md.transform/default-hiccup-renderers
        ;; :text is funkier when it's teal
        :text (fn [_ctx node] [:span {:style {:color "teal"}} (:text node)])
        ;; :paragraphs linebreaks are too damn high 🐜
        :paragraph (partial md.transform/into-markup [:p {:style {:margin-top "-1.6rem"}}])
        ;; :ruler gets to be funky, too
        :ruler (constantly [:hr {:style {:border "2px dashed teal"}}]))
 data)

Extensibility 🐢

We added minimal tooling for extending markdown expressions. See the linked notebook for an extended example.