comrak 0.2.5

A 100% CommonMark-compatible GitHub Flavored Markdown parser and formatter

Build Status Spec Status: 647/647 crates.io version docs.rs

Rust port of github's cmark-gfm.

Usage

A binary is included which does everything you typically want:

$ comrak --help
comrak 0.2.5
Ashe Connor <kivikakk@github.com>
A 100% CommonMark-compatible GitHub Flavored Markdown parser and formatter

USAGE:
    comrak [FLAGS] [OPTIONS] [--] [FILE]...

FLAGS:
        --footnotes          Parse footnotes
        --github-pre-lang    Use GitHub-style <pre lang> for code blocks
        --hardbreaks         Treat newlines as hard line breaks
    -h, --help               Prints help information
        --prepare-regexes    Prepare regexes up front for benchmarking
    -V, --version            Prints version information

OPTIONS:
    -e, --extension <EXTENSION>...    Specify an extension name to use [values: strikethrough, tagfilter, table, autolink, tasklist, superscript, footnotes]
    -t, --to <FORMAT>                 Specify output format [default: html]  [values: html, commonmark]
        --header-ids <PREFIX>         Use the Comrak header IDs extension, with the given ID prefix
        --width <WIDTH>               Specify wrap width (0 = nowrap) [default: 0]

ARGS:
    <FILE>...    The CommonMark file to parse; or standard input if none passed

And there's a Rust interface. You can use comrak::markdown_to_html directly:

use comrak::{markdown_to_html, ComrakOptions};
assert_eq!(markdown_to_html("Hello, **世界**!", &ComrakOptions::default()),
           "<p>Hello, <strong>世界</strong>!</p>\n");

Or you can parse the input into an AST yourself, manipulate it, and then use your desired formatter:

extern crate comrak;
extern crate typed_arena;
use typed_arena::Arena;
use comrak::{parse_document, format_html, ComrakOptions};
use comrak::nodes::{AstNode, NodeValue};

// The returned nodes are created in the supplied Arena, and are bound by its lifetime.
let arena = Arena::new();

let root = parse_document(
    &arena,
    "This is my input.\n\n1. Also my input.\n2. Certainly my input.\n",
    &ComrakOptions::default());

fn iter_nodes<'a, F>(node: &'a AstNode<'a>, f: &F)
    where F : Fn(&'a AstNode<'a>) {
    f(node);
    for c in node.children() {
        iter_nodes(c, f);
    }
}

iter_nodes(root, &|node| {
    match &mut node.data.borrow_mut().value {
        &mut NodeValue::Text(ref mut text) => {
            let orig = std::mem::replace(text, vec![]);
            *text = String::from_utf8(orig).unwrap().replace("my", "your").as_bytes().to_vec();
        }
        _ => (),
    }
});

let mut html = vec![];
format_html(root, &ComrakOptions::default(), &mut html).unwrap();

assert_eq!(
    String::from_utf8(html).unwrap(),
    "<p>This is your input.</p>\n\
     <ol>\n\
     <li>Also your input.</li>\n\
     <li>Certainly your input.</li>\n\
     </ol>\n");

Extensions

Comrak supports the five extensions to CommonMark defined in the GitHub Flavored Markdown Spec:

as well as superscript and footnotes.

By default none are enabled; they are individually enabled with each parse by setting the appropriate values in the ComrakOptions struct.

Legal

Copyright (c) 2017, Ashe Connor. Licensed under the 2-Clause BSD License.

cmark itself is is copyright (c) 2014, John MacFarlane.

See COPYING for all the details.

Contributors

Thank you for PRs and issues opened!