MDEx

Fast and Extensible Markdown for Elixir.

Features

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

Examples

Livebook examples are available at Pages / Examples

Installation

Add :mdex dependency:

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

Usage

iex> MDEx.to_html!("# Hello :smile:", extension: [shortcodes: true])
"<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{nodes: [%MDEx.Heading{nodes: [%MDEx.Text{literal: "Hello "}, %MDEx.ShortCode{code: "smile", emoji: "😄"}], level: 1, setext: false}]}

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	✅	❌	❌	❌
AST	✅	✅	✅	❌
AST to Markdown	✅	⚠️²	❌	❌
To HTML	✅	✅	✅	✅
To JSON	✅	❌	❌	❌
To XML	✅	❌	❌	✅
To Manpage	❌	❌	❌	✅
To LaTeX	❌	❌	❌	✅
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 simple script is available to compare existing libs:

Name              ips        average  deviation         median         99th %
cmark          7.17 K       0.139 ms     ±4.20%       0.138 ms       0.165 ms
mdex           2.71 K        0.37 ms     ±7.95%        0.36 ms        0.45 ms
md            0.196 K        5.11 ms     ±2.51%        5.08 ms        5.55 ms
earmark      0.0372 K       26.91 ms     ±2.09%       26.77 ms       30.25 ms

Comparison:
cmark          7.17 K
mdex           2.71 K - 2.65x slower +0.23 ms
md            0.196 K - 36.69x slower +4.98 ms
earmark      0.0372 K - 193.04x slower +26.77 ms

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

Comparison:
mdex_sigil_MD    176948.46 K
cmark                31.47 K - 5622.76x slower +31.77 μs
mdex_to_html/1        7.32 K - 24184.36x slower +136.67 μs
md                    2.05 K - 86176.93x slower +487.01 μs
earmark               0.21 K - 855844.67x slower +4836.68 μs

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