# 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][]** (GFM, MDX, frontmatter, math)
- [x] **[safe][security]** (100% safe rust, also 100% safe HTML by default)
- [x] **[robust][test]** (2300+ tests, 100% coverage)
It’s also `#![no_std]` + `alloc`, has tons of docs, and has a single dependency
(for optional debug logging).
> 🐣 **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)
- [Architecture](#architecture)
- [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, Constructs, Options};
fn main() -> Result<(), String> {
println!(
"{}",
micromark_with_options(
"* [x] contact@example.com ~~strikethrough~~",
&Options {
constructs: Constructs::gfm(),
..Options::default()
}
)?
);
Ok(())
}
```
Yields:
```html
```
## 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), and
[`Options`](https://wooorm.com/micromark-rs/micromark/struct.Options.html).
See [crate docs][docs] for more info.
## Extensions
micromark supports extensions.
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
- JSX (agnostic of JavaScript)
- expressions (agnostic of JavaScript)
It’s planned to add support for integrating with SWC for MDX JSX and expressions
that is aware of JavaScript syntax, and for ESM (import/export).
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.
## Architecture
micromark is maintained as a single monolithic package.
### Overview
The process to parse markdown looks like this:
```txt
micromark
+------------------------------------------------+
| +-------+ +---------+ |
| -markdown->+ parse +-events->+ compile +-html- |
| +-------+ +---------+ |
+------------------------------------------------+
```
### File structure
The files in `src/` are as follows:
- `construct/*.rs`
— CommonMark, GFM, and other extension constructs used in micromark
- `util/*.rs`
— helpers often needed when parsing markdown
- `compiler.rs`
— turns events into a string of HTML
- `event.rs`
— things with meaning happening somewhere
- `lib.rs`
— core module
- `parser.rs`
— turn a string of markdown into events
- `resolve.rs`
— steps to process events
- `state.rs`
— steps of the state machine
- `subtokenize.rs`
— handle content in other content
- `tokenizer.rs`
— glue the states of the state machine together
## 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 the `` being swapped with:
```html