# micromark-rs
[![Chat][chat-badge]][chat]
CommonMark compliant markdown parser in Rust with ASTs and extensions.
## Feature highlights
* [x] **[compliant][commonmark]** (100% to CommonMark)
* [x] **[extensions][]** (100% GFM, 100% MDX, frontmatter, math)
* [x] **[safe][security]** (100% safe Rust, also 100% safe HTML by default)
* [x] **[robust][test]** (2300+ tests, 100% coverage, fuzz testing)
* [x] **[ast][mdast]** (mdast)
## When should I use this?
* If you *just* want to turn markdown into HTML (with maybe a few extensions)
* If you want to do *really complex things* with markdown
## What is this?
micromark is an open source markdown parser written in Rust.
It’s implemented as a state machine (`#![no_std]` + `alloc`) that emits
concrete tokens, so that every byte is accounted for, with positional info.
The API then exposes this information as an AST, which is easier to work with,
or it compiles directly to HTML.
While most markdown parsers work towards compliancy with CommonMark (or GFM),
this project goes further by following how the reference parsers (`cmark`,
`cmark-gfm`) work, which is confirmed with thousands of extra tests.
Other than CommonMark and GFM, this project also supports common extensions
to markdown such as MDX, math, and frontmatter.
## Questions
* to learn markdown, see this [cheatsheet and tutorial][cheat]
* for the API, see the [crate docs][docs]
* for questions, see [Discussions][chat]
* to help, see [contribute][] or [sponsor][] below
## Contents
* [Install](#install)
* [Use](#use)
* [API](#api)
* [Extensions](#extensions)
* [Examples](#examples)
* [Example: syntax highlighting code](#example-syntax-highlighting-code)
* [Markdown](#markdown)
* [CommonMark](#commonmark)
* [Grammar](#grammar)
* [Project](#project)
* [Overview](#overview)
* [File structure](#file-structure)
* [Test](#test)
* [Version](#version)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## Install
With [Rust][] (rust edition 2018+, ±version 1.56+), install with `cargo`:
```sh
cargo install micromark
```
## Use
```rs
extern crate micromark;
use micromark::micromark;
fn main() {
println!("{}", micromark("## Hello, *world*!"));
}
```
Yields:
```html
Hello, world!
```
Extensions (in this case GFM):
```rs
extern crate micromark;
use micromark::{micromark_with_options, Options};
fn main() -> Result<(), String> {
println!(
"{}",
micromark_with_options(
"* [x] contact@example.com ~~strikethrough~~",
&Options::gfm()
)?
);
Ok(())
}
```
Yields:
```html
```
Syntax tree ([mdast][]):
```rs
extern crate micromark;
use micromark::{micromark_to_mdast, ParseOptions};
fn main() -> Result<(), String> {
println!(
"{:?}",
micromark_to_mdast("# Hey, *you*!", &ParseOptions::default())?
);
Ok(())
}
```
Yields:
```text
Root { children: [Heading { children: [Text { value: "Hey, ", position: Some(1:3-1:8 (2-7)) }, Emphasis { children: [Text { value: "you", position: Some(1:9-1:12 (8-11)) }], position: Some(1:8-1:13 (7-12)) }, Text { value: "!", position: Some(1:13-1:14 (12-13)) }], position: Some(1:1-1:14 (0-13)), depth: 1 }], position: Some(1:1-1:14 (0-13)) }
```
## API
`micromark` exposes
[`micromark`](https://wooorm.com/micromark-rs/micromark/fn.micromark.html),
[`micromark_with_options`](https://wooorm.com/micromark-rs/micromark/fn.micromark_with_options.html),
[`micromark_to_mdast`](https://wooorm.com/micromark-rs/micromark/fn.micromark_to_mdast.html),
[`Options`](https://wooorm.com/micromark-rs/micromark/struct.Options.html),
and a few other structs and enums.
See the [crate docs][docs] for more info.
## Extensions
micromark supports extensions to `CommonMark`.
These extensions are maintained in this project.
They are not enabled by default but can be turned on with options.
* frontmatter
* GFM
* autolink literal
* footnote
* strikethrough
* table
* tagfilter
* task list item
* math
* MDX
* ESM
* expressions
* JSX
It is not a goal of this project to support lots of different extensions.
It’s instead a goal to support very common and mostly standardized extensions.
## Examples
### Example: syntax highlighting code
This example shows how `micromark-rs` can be used to turn markdown into an HTML
file.
When the HTML is opened in a browser, the code examples that were in the
markdown are then syntax highlighted by client side JavaScript using
[`starry-night`][starry-night].
The `starry-night` library matches how GitHub highlights code on their platform.
Say we have this `example.rs`:
```rs
extern crate micromark;
use micromark::{micromark_with_options, Constructs, Options};
use std::fs;
fn main() -> Result<(), String> {
let markdown = r###"
# Hello
…world!
~~~js
console.log('it works!')
~~~
"###;
let html = micromark_with_options(
markdown,
&Options {
constructs: Constructs::gfm(),
..Options::default()
},
)?;
let js = r###"
import {createStarryNight, common} from 'https://esm.sh/@wooorm/starry-night@1?bundle'
import {toDom} from 'https://esm.sh/hast-util-to-dom@3?bundle'
const starryNight = await createStarryNight(common)
const prefix = 'language-'
const nodes = Array.from(document.body.querySelectorAll('code'))
for (const node of nodes) {
const className = Array.from(node.classList).find((d) => d.startsWith(prefix))
if (!className) continue
const scope = starryNight.flagToScope(className.slice(prefix.length))
if (!scope) continue
const tree = starryNight.highlight(node.textContent, scope)
node.replaceChildren(toDom(tree, {fragment: true}))
}
"###;
let html = format!(
"
Hello
{}
",
html, js
);
match fs::write("index.html", html) {
Ok(()) => {}
Err(error) => return Err(format!("Could not write `index.html`: {:?}", error)),
}
Ok(())
}
```
The code example in the markdown as HTML will first look like this:
```html
console.log('it works!')
```
Opening the document in a browser, we’d see it being swapped with:
```html