markdown-rs

Extensions are not enabled by default. You can enable them by passing specific Options to to_html_with_options. Supported extensions include:

• GFM: autolink literal, footnote, strikethrough, table, tagfilter, task list item.
• MDX: ESM, expressions, JSX.
• frontmatter
• math

The library is implemented as a state machine (#![no_std] + alloc) that emits concrete tokens. The high-level process follows this flow:

1. Parse: The input string is turned into a stream of events.
2. Resolve: Events are processed and resolved.
3. Compile: Events are compiled into either an HTML string or an mdast syntax tree.

To use markdown-rs in your Rust project (requires Rust edition 2018+ and version 1.56+), add it using cargo add.

cargo add markdown

In markdown-rs, a Document represents the top-level containers that structure the markdown content. These containers hold other sections and define the document's flow.

Common flow constructs include:

• Block quote
• List item
• GFM: Footnote definition

The document lifecycle involves handling optional components like the Byte Order Mark (BOM) and frontmatter before processing these structural containers.

Most nodes in the markdown-rs AST share common fields for managing content and metadata:

• children: A Vec<Node> representing the nested content model (used by parent nodes like Root, Paragraph, Table, etc.).
• position: An Option<Position> providing the location of the node in the source text.
• value: A String representing the literal text content (used by leaf nodes like Text, Code, Yaml, etc.).
• stops: A Vec<Stop> used in MDX nodes to track the source slices of the value string (serialized as _markdownRsStops).

XSS Protection

markdown-rs is safe by default. It encodes or drops embedded HTML and dangerous protocols (like javascript:) to prevent Cross-Site Scripting (XSS).

Warning: Enabling allow_dangerous_html or allow_dangerous_protocol via options makes your application vulnerable to XSS if you are processing untrusted user input.

Image Sources

By default, the parser only allows http:, https:, and relative image sources. You can safely enable allow_any_img_src as modern browsers protect against scripts in images.

Denial of Service (DoS)

To protect against resource exhaustion attacks (e.g., extremely large files or deeply nested syntax like unclosed emphasis/links):

1. Cap the accepted input size (e.g., 500kb).
2. Process content in a separate thread so it can be interrupted if needed.

You can convert markdown strings directly to HTML using markdown::to_html. For more control, use markdown::to_html_with_options which allows you to enable extensions like GFM (GitHub Flavored Markdown). Note that to_html_with_options returns a Result<String, Message>, so you must handle potential errors (especially when using MDX).

// Basic usage
println!("{}", markdown::to_html("## Hi, *Saturn*! 🪐"));

// Usage with GFM extensions
fn main() -> Result<(), markdown::message::Message> {
    println!(
        "{}",
        markdown::to_html_with_options(
            "* [x] contact ~Mercury~Venus at hi@venus.com!",
            &markdown::Options::gfm()
        )?
    );
    Ok(())
}

To perform complex manipulations on the markdown structure, you can parse it into an mdast (Markdown Abstract Syntax Tree) using markdown::to_mdast. This requires providing markdown::ParseOptions.

fn main() -> Result<(), markdown::message::Message> {
    println!(
        "{:?}",
        markdown::to_mdast("# Hi *Earth*!", &markdown::ParseOptions::default())?
    );
    Ok(())
}

The crate provides several optional features to extend its functionality:

• log: Enables logging. You can view logs by setting the environment variable RUST_LOG=debug.
• serde: Enables serde support, allowing you to serialize and deserialize ASTs and configuration objects.

Note: The default feature is enabled by default but provides no additional functionality (nothing is enabled by default).

You can fine-tune the parser by modifying the constructs field within ParseOptions. This allows you to selectively enable or disable specific markdown features (e.g., turning off indented code blocks while keeping other features).

use markdown::{to_html_with_options, Constructs, Options, ParseOptions};
# fn main() -> Result<(), markdown::message::Message> {

// Pass `constructs` to choose what to enable and disable:
assert_eq!(to_html_with_options(
    "    indented code?",
    &Options {
        parse: ParseOptions {
          constructs: Constructs {
            code_indented: false,
            ..Constructs::default()
          },
          ..ParseOptions::default()
        },
        ..Options::default()
    }
)?,
    "<p>indented code?</p>"
);
# Ok(())
# }