MDEx

<div align="center"> <img src="https://raw.githubusercontent.com/leandrocp/mdex/main/assets/images/mdex_logo.png" width="360" alt="MDEx logo" /> <br> <a href="https://hex.pm/packages/mdex"> <img alt="Hex Version" src="https://img.shields.io/hexpm/v/mdex"> </a> <a href="https://hexdocs.pm/mdex"> <img alt="Hex Docs" src="http://img.shields.io/badge/hex.pm-docs-green.svg?style=flat"> </a> <a href="https://opensource.org/licenses/MIT"> <img alt="MIT" src="https://img.shields.io/hexpm/l/mdex"> </a> <p align="center">Fast and Extensible Markdown for Elixir.</p> </div>

Features

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

Plugins

mdex_gfm - Enable GitHub Flavored Markdown (GFM)
mdex_mermaid - Render Mermaid diagrams in code blocks
mdex_katex - Render math formulas using KaTeX
mdex_video_embed - Privacy-respecting video embeds from code blocks
mdex_custom_heading_id - Custom heading IDs for markdown headings
mdex_mermex - Render Mermaid diagrams server-side using Mermex (Rust NIF)

Installation

Add :mdex dependency:

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

Or use Igniter:

mix igniter.install mdex

Usage

Convert to HTML

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

GitHub Flavored Markdown (GFM)

Using the :html_multi_themes syntax highlighting formatter is not required but you get light/dark using it.

Mix.install([
  {:mdex_gfm, "~> 0.1"}
])

markdown = """
- [x] Set up project
- [ ] Write docs

```elixir
spawn(fn -> send(current, {self(), 1 + 2}) end)
```
"""

MDEx.new(
  markdown: markdown,
  syntax_highlight: [
    formatter: {:html_multi_themes,
      themes: [light: "github_light", dark: "github_dark"],
      default_theme: "light-dark()"}
  ]
)
|> MDExGFM.attach()
|> MDEx.to_html!()

Sigils

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

iex> import MDEx.Sigil
iex> assigns = %{project: "MDEx"}
iex> ~MD[# {@project}]HEEX
%Phoenix.LiveView.Rendered{...}

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: "😄"
>

Streaming

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

Examples and Guides

In docs you can find Livebook examples covering options and usage, and Guides for more info.

Foundation

The library is built on top of:

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

Used By

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)|✅|❌|❌|❌| |Phoenix HEEx components|✅|❌|❌|❌| |AST|✅|✅|✅|❌| |AST to Markdown|✅|⚠️²|❌|❌| |To HTML|✅|✅|✅|✅| |To JSON|✅|❌|❌|❌| |To XML|✅|❌|❌|✅| |To Manpage|❌|❌|❌|✅| |To LaTeX|❌|❌|❌|✅| |To Quill Delta|✅|❌|❌|❌| |Emoji|✅|❌|❌|❌| |GFM³|✅|✅|❌|❌| |GLFM⁴|✅|❌|❌|❌| |Discord⁵|⚠️¹|❌|❌|❌|

Partial support
Possible with earmark_reversal
GitHub Flavored Markdown
GitLab Flavored Markdown
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

Mdex

Install / Use

README