# micromark-rs
[![Sponsors][sponsors-badge]][opencollective]
[![Backers][backers-badge]][opencollective]
[![Chat][chat-badge]][chat]
A [`CommonMark`][commonmark-spec] compliant markdown parser in [Rust][] with
positional info, concrete tokens, and extensions.
## Feature highlights
- [x] **[compliant][commonmark]** (100% to CommonMark)
- [x] **[extensions][]** (100% GFM, 100% MDX, frontmatter, math)
- [x] **[ast][mdast]** (mdast)
- [x] **[safe][security]** (100% safe rust, also 100% safe HTML by default)
- [x] **[robust][test]** (2300+ tests, 100% coverage, fuzz testing)
It’s also `#![no_std]` + `alloc` and has tons of docs.
> 🐣 **Note**: coverage is currently within progress.
## When to 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
See [§ Comparison][comparison] for more info
## Intro
micromark is markdown parser in Rust.
It uses a state machine to parse the entirety of markdown into concrete
tokens.
Its API compiles to HTML, but its parts are made to be used separately, so as to
generate syntax trees or compile to other output formats.
`micromark-rs` has a sibling in JavaScript, [`micromark-js`][micromark-js].
- to learn markdown, see this [cheatsheet and tutorial][cheat]
- for questions, see [Discussions][chat]
- to help, see [contribute][] or [sponsor][] below
## Contents
- [Install](#install)
- [Use](#use)
- [API](#api)
- [Extensions](#extensions)
- [Examples](#examples)
- [Markdown](#markdown)
- [Project](#project)
- [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 incredibly common, somewhat standardized,
extensions.
## Examples
> 🚧 **To do**.
### 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 that page in a browser, we’d see that being swapped with:
```html