MDEx

Fast and Extensible Markdown for Elixir.

Features

• Fast
• Compliant with the CommonMark spec
• Plugins
• Formats:
  • Markdown (CommonMark)
  • HTML
  • JSON
  • XML
  • Quill Delta
• Floki-like Document AST
• Req-like Document pipeline API
• GitHub Flavored Markdown
• Discord and GitLab Flavored-ish Markdown
• Wiki-style links
• Streaming incomplete fragments
• Emoji shortcodes
• Built-in Syntax Highlighting for code blocks
• Code Block Decorators
• HTML sanitization
• ~MD Sigil for Markdown, HTML, JSON, XML, and Quill Delta

Examples

Livebook examples are available at Pages / Examples

Installation

Add :mdex dependency:

def deps do
  [
    {:mdex, "~> 0.8"}
  ]
end

Or use Igniter:

mix igniter.install mdex

Usage

iex> MDEx.to_html!("# Hello :smile:", extension: [shortcodes: true])
"<h1>Hello 😄</h1>"

iex> MDEx.new(markdown: "# Hello :smile:", extension: [shortcodes: true]) |> MDEx.to_html!()
"<h1>Hello 😄</h1>"

iex> import MDEx.Sigil
iex> ~MD[# Hello :smile:]HTML
"<h1>Hello 😄</h1>"

iex> import MDEx.Sigil
iex> ~MD[# Hello :smile:]
#MDEx.Document(3 nodes)<
├── 1 [heading] level: 1, setext: false
│   ├── 2 [text] literal: "Hello "
│   └── 3 [short_code] code: "smile", emoji: "😄"
>

iex> MDEx.new(streaming: true)
...> |> MDEx.Document.put_markdown("**Install")
...> |> MDEx.to_html!()
"<p><strong>Install</strong></p>"

Foundation

The library is built on top of:

• comrak - a fast Rust port of GitHub's CommonMark parser
• ammonia for HTML Sanitization
• autumnus for Syntax Highlighting

Used By

• BeaconCMS
• Tableau
• Bonfire
• 00
• Plural Console
• Exmeralda
• Algora
• Ash AI
• Canada Navigator
• And more...

Are you using MDEx and want to list your project here? Please send a PR!

Motivation

MDEx was born out of the necessity of parsing CommonMark files, to parse hundreds of files quickly, and to be easily extensible by consumers of the library.

• earmark is extensible but can't parse all kinds of documents and is slow to convert hundreds of markdowns.
• md is very extensible but the doc says "If one needs to perfectly parse the common markdown, Md is probably not the correct choice" and CommonMark was a requirement to parse many existing files.
• markdown is not precompiled and has not received updates in a while.
• cmark is a fast CommonMark parser but it requires compiling the C library, is hard to extend, and was archived on Apr 2024.

Comparison

Feature	MDEx	Earmark	md	cmark
Active	✅	✅	✅	❌
Pure Elixir	❌	✅	✅	❌
Extensible	✅	✅	✅	❌
Syntax Highlighting	✅	❌	❌	❌
Code Block Decorators	✅	❌	❌	❌
Streaming (fragments)	✅	❌	❌	❌
AST	✅	✅	✅	❌
AST to Markdown	✅	⚠️²	❌	❌
To HTML	✅	✅	✅	✅
To JSON	✅	❌	❌	❌
To XML	✅	❌	❌	✅
To Manpage	❌	❌	❌	✅
To LaTeX	❌	❌	❌	✅
To Quill Delta	✅	❌	❌	❌
Emoji	✅	❌	❌	❌
GFM³	✅	✅	❌	❌
GitLab⁴	⚠️¹	❌	❌	❌
Discord⁵	⚠️¹	❌	❌	❌

1. Partial support
2. Possible with earmark_reversal
3. GitHub Flavored Markdown
4. GitLab Flavored Markdown
5. Discord Flavored Markdown

Benchmark

A benchmark is available to compare existing libs:

Name              ips        average  deviation         median         99th %
mdex          8983.16       0.111 ms     ±6.52%       0.110 ms       0.144 ms
md             461.00        2.17 ms     ±2.64%        2.16 ms        2.35 ms
earmark        110.47        9.05 ms     ±3.17%        9.02 ms       10.01 ms

Comparison:
mdex          8983.16
md             461.00 - 19.49x slower +2.06 ms
earmark        110.47 - 81.32x slower +8.94 ms

Memory usage statistics:

Name            average  deviation         median         99th %
mdex         0.00184 MB     ±0.00%     0.00184 MB     0.00184 MB
md              6.45 MB     ±0.00%        6.45 MB        6.45 MB
earmark         5.09 MB     ±0.00%        5.09 MB        5.09 MB

Comparison:
mdex         0.00184 MB
md              6.45 MB - 3506.37x memory usage +6.45 MB
earmark         5.09 MB - 2770.15x memory usage +5.09 MB

The most performance gain is using the ~MD sigil to compile the Markdown instead of parsing it at runtime, prefer using it when possible.

To finish, a friendly reminder that all libs have their own strengths and trade-offs so use the one that better suits your needs.

Acknowledgements

• comrak crate for all the heavy work on parsing Markdown and rendering HTML
• Floki for the AST
• Req for the pipeline API
• Logo based on markdown-mark