Padmark

Padmark is a pure-Elixir Markdown to HTML converter. It has no native dependencies, no NIFs and no external binaries, so it compiles and runs anywhere Elixir does, including inside a Mix escript.

It can be used as a library (Padmark.as_html/2) or as a command-line tool (mix escript.build).

Rationale

Padmark is a fork of Earmark, created and maintained for years by Dave Thomas and Robert Dober. Earmark is the library Lambdapad has used since its first release to turn Markdown into HTML, and it is a solid, well-tested piece of software. Thank you to both of you for it.

Hex now lists Earmark as retired, with this notice from its own maintainers:

Earmark is no longer maintained. Migrate to a replacement, for example MDEx.

We looked at MDEx, the suggested replacement. It is a good library, but it renders Markdown through comrak, a Rust library, wired in through a NIF. That is a fine trade-off for a web application, but not for Lambdapad: lpad, Lambdapad's CLI, ships as a Mix escript, a single self-contained file. Escripts cannot load a NIF, because a NIF needs its compiled .so file to sit in a real priv/ directory on disk, and an escript has no such thing, only a zipped bundle of .beam files. A dependency on MDEx would mean lpad crashing on the first real Markdown file it tried to render.

So instead of switching to a library that cannot work for us, we forked Earmark under Lambdapad and picked up where its authors left off: fixing the security issue that got it retired in the first place (a stored XSS via unescaped HTML attribute values), a couple of other bugs found along the way, and adding tests where there were none. Padmark will keep being maintained here for as long as Lambdapad needs a pure-Elixir Markdown converter, which is to say, for as long as Lambdapad itself is maintained.

Usage

Padmark.as_html!("# Hello Padmark")
# "<h1>\nHello Padmark</h1>\n"

{:ok, html, []} = Padmark.as_html("*emphasis* and **strong**")
html
# "<p>\n<em>emphasis</em> and <strong>strong</strong></p>\n"

See the moduledocs of Padmark, Padmark.Options and Padmark.Transform for the full set of options (footnotes, GFM tables, subscript/superscript, postprocessors, AST traversal, and more).

Installation

Padmark is not published on Hex. Add it as a git dependency in mix.exs:

def deps do
  [
    {:padmark, github: "lambdapad/padmark"}
  ]
end

License

Padmark is licensed under the Apache License 2.0, the same license Earmark was released under.