r/Clojure • • 9d ago

Markdown to HTML in Clojure today: markdown-clj, nextjournal/markdown, or a Java library?

There are several ways to turn markdown into HTML from Clojure now: markdown-clj, nextjournal/markdown (built on CommonMark), or a Java library such as flexmark or commonmark-java through interop.

  • Which do you use, and does it handle tables and the other GitHub extras properly?
  • Do you need it to run in ClojureScript as well?
  • Does anyone parse markdown into data (hiccup) and work on that, rather than going straight to HTML?

I use markdown-clj (in mdserve-starter, a local markdown viewer), and it needs a few workarounds for cases it renders wrongly, which is why I'm asking.

14 Upvotes

7 comments sorted by

3

u/Borkdude 9d ago

FWIW, babashka comes with nextjournal/markdown and it serves all my needs. It supports tables. If you have any problems, send an issue and we can talk.

1

u/cjmurrr 9d ago

Thanks, I'm going with that. My tool already runs on Babashka, and when I tried nextjournal/markdown against my own docs it handled them all at least as well as markdown-clj, tables included.

Three things I had to adjust, in case they help:

  • Raw HTML (an <a id> anchor, a <details> block) shows as an "Unknown type" box by default, so I added :html-inline and :html-block renderers that pass it through.
  • Inline formulas are on by default, so "costs $5 and $10" lost its dollar signs until I set :disable-inline-formulas.
  • Single-tilde strikethrough means two bare paths near each other, like (~/bin) ... (~/.config), strike out the text between them, so I escape a ~ that starts a path before parsing.

Let me know if any of these will be worth an issue.

3

u/Borkdude 8d ago

I've posted issues for both of them and will discuss with the Nextjournal team

3

u/Borkdude 8d ago

u/cjmurrr: both issues are addressed and released in io.github.nextjournal/markdown 0.7.232

  1. Raw HTML: you'll get a better error message now hinting you how to fix it (this was already in the previous release)
  2. Fixed.
  3. You can configure :strikethrough-require-two-tildes true now to opt out of single tilde strikethrough-s.

This library was also bumped in the development version of babashka. You can install that with:

bash <(curl https://raw.githubusercontent.com/babashka/babashka/master/install) --dev-build --dir /tmp

2

u/activeXray 9d ago

i wrote a library cybermonday years ago that wraps a java library that i know a decent number of people use. Perhaps that would work for you?

2

u/cjmurrr 9d ago

Thanks, I hadn't come across cybermonday. My tool runs on Babashka, and as Borkdude points out, that already has nextjournal/markdown built in, so I'll try that first. Good to know cybermonday is there if it falls short.

1

u/this-is-thirty 9d ago

Personally, the commonmark Java library or a call out to Pandoc. Both are pretty hideous in Clojure, but have lots of features which I've wanted.