Struct RenderOptions

Source

pub struct RenderOptions {Show 17 fields
    pub hardbreaks: bool,
    pub github_pre_lang: bool,
    pub full_info_string: bool,
    pub width: usize,
    pub unsafe_: bool,
    pub escape: bool,
    pub list_style: ListStyleType,
    pub sourcepos: bool,
    pub experimental_inline_sourcepos: bool,
    pub escaped_char_spans: bool,
    pub ignore_setext: bool,
    pub ignore_empty_links: bool,
    pub gfm_quirks: bool,
    pub prefer_fenced: bool,
    pub figure_with_caption: bool,
    pub tasklist_classes: bool,
    pub ol_width: usize,
}

Expand description

Options for formatter functions.

Fields§

§hardbreaks: bool

Soft line breaks in the input translate into hard line breaks in the output.

let mut options = Options::default();
assert_eq!(markdown_to_html("Hello.\nWorld.\n", &options),
           "<p>Hello.\nWorld.</p>\n");

options.render.hardbreaks = true;
assert_eq!(markdown_to_html("Hello.\nWorld.\n", &options),
           "<p>Hello.<br />\nWorld.</p>\n");

§github_pre_lang: bool

GitHub-style <pre lang="xyz"> is used for fenced code blocks with info tags.

let mut options = Options::default();
assert_eq!(markdown_to_html("``` rust\nfn hello();\n```\n", &options),
           "<pre><code class=\"language-rust\">fn hello();\n</code></pre>\n");

options.render.github_pre_lang = true;
assert_eq!(markdown_to_html("``` rust\nfn hello();\n```\n", &options),
           "<pre lang=\"rust\"><code>fn hello();\n</code></pre>\n");

§full_info_string: bool

Enable full info strings for code blocks

let mut options = Options::default();
assert_eq!(markdown_to_html("``` rust extra info\nfn hello();\n```\n", &options),
           "<pre><code class=\"language-rust\">fn hello();\n</code></pre>\n");

options.render.full_info_string = true;
let html = markdown_to_html("``` rust extra info\nfn hello();\n```\n", &options);
assert!(html.contains(r#"data-meta="extra info""#));

§width: usize

The wrap column when outputting CommonMark.

let mut options = Options::default();
let node = parse_document(&arena, "hello hello hello hello hello hello", &options);
let mut output = vec![];
format_commonmark(node, &options, &mut output).unwrap();
assert_eq!(String::from_utf8(output).unwrap(),
           "hello hello hello hello hello hello\n");

options.render.width = 20;
let mut output = vec![];
format_commonmark(node, &options, &mut output).unwrap();
assert_eq!(String::from_utf8(output).unwrap(),
           "hello hello hello\nhello hello hello\n");

§unsafe_: bool

Allow rendering of raw HTML and potentially dangerous links.

let mut options = Options::default();
let input = "<script>\nalert('xyz');\n</script>\n\n\
             Possibly <marquee>annoying</marquee>.\n\n\
             [Dangerous](javascript:alert(document.cookie)).\n\n\
             [Safe](http://commonmark.org).\n";

assert_eq!(markdown_to_html(input, &options),
           "<!-- raw HTML omitted -->\n\
            <p>Possibly <!-- raw HTML omitted -->annoying<!-- raw HTML omitted -->.</p>\n\
            <p><a href=\"\">Dangerous</a>.</p>\n\
            <p><a href=\"http://commonmark.org\">Safe</a>.</p>\n");

options.render.unsafe_ = true;
assert_eq!(markdown_to_html(input, &options),
           "<script>\nalert(\'xyz\');\n</script>\n\
            <p>Possibly <marquee>annoying</marquee>.</p>\n\
            <p><a href=\"javascript:alert(document.cookie)\">Dangerous</a>.</p>\n\
            <p><a href=\"http://commonmark.org\">Safe</a>.</p>\n");

§escape: bool

Escape raw HTML instead of clobbering it.

let mut options = Options::default();
let input = "<i>italic text</i>";

assert_eq!(markdown_to_html(input, &options),
           "<p><!-- raw HTML omitted -->italic text<!-- raw HTML omitted --></p>\n");

options.render.escape = true;
assert_eq!(markdown_to_html(input, &options),
           "<p>&lt;i&gt;italic text&lt;/i&gt;</p>\n");

§list_style: ListStyleType

Set the type of bullet list marker to use. Options are:

ListStyleType::Dash to use - (default)
ListStyleType::Plus to use +
ListStyleType::Star to use *

let mut options = Options::default();
let input = "- one\n- two\n- three";
assert_eq!(markdown_to_commonmark(input, &options),
           "- one\n- two\n- three\n"); // default is Dash

options.render.list_style = ListStyleType::Plus;
assert_eq!(markdown_to_commonmark(input, &options),
           "+ one\n+ two\n+ three\n");

options.render.list_style = ListStyleType::Star;
assert_eq!(markdown_to_commonmark(input, &options),
           "* one\n* two\n* three\n");

§sourcepos: bool

Include source position attributes in HTML and XML output.

Sourcepos information is reliable for all core block items, and most extensions. The description lists extension still has issues; see https://github.com/kivikakk/comrak/blob/3bb6d4ce/src/tests/description_lists.rs#L60-L125.

Sourcepos information is not reliable for inlines, and is not included in HTML without also setting experimental_inline_sourcepos. See https://github.com/kivikakk/comrak/pull/439 for a discussion.

let mut options = Options::default();
options.render.sourcepos = true;
let input = "## Hello world!";
let xml = markdown_to_commonmark_xml(input, &options);
assert!(xml.contains("<text sourcepos=\"1:4-1:15\" xml:space=\"preserve\">"));

§experimental_inline_sourcepos: bool

Include inline sourcepos in HTML output, which is known to have issues. See https://github.com/kivikakk/comrak/pull/439 for a discussion.

let mut options = Options::default();
options.render.sourcepos = true;
let input = "Hello *world*!";
assert_eq!(markdown_to_html(input, &options),
           "<p data-sourcepos=\"1:1-1:14\">Hello <em>world</em>!</p>\n");
options.render.experimental_inline_sourcepos = true;
assert_eq!(markdown_to_html(input, &options),
           "<p data-sourcepos=\"1:1-1:14\">Hello <em data-sourcepos=\"1:7-1:13\">world</em>!</p>\n");

§escaped_char_spans: bool

Wrap escaped characters in a  to allow any post-processing to recognize them.

let mut options = Options::default();
let input = "Notify user \\@example";

assert_eq!(markdown_to_html(input, &options),
           "<p>Notify user @example</p>\n");

options.render.escaped_char_spans = true;
assert_eq!(markdown_to_html(input, &options),
           "<p>Notify user <span data-escaped-char>@</span>example</p>\n");

§ignore_setext: bool

Ignore setext headings in input.

let mut options = Options::default();
let input = "setext heading\n---";

assert_eq!(markdown_to_html(input, &options),
           "<h2>setext heading</h2>\n");

options.render.ignore_setext = true;
assert_eq!(markdown_to_html(input, &options),
           "<p>setext heading</p>\n<hr />\n");

§ignore_empty_links: bool

Ignore empty links in input.

let mut options = Options::default();
let input = "[]()";

assert_eq!(markdown_to_html(input, &options),
           "<p><a href=\"\"></a></p>\n");

options.render.ignore_empty_links = true;
assert_eq!(markdown_to_html(input, &options), "<p>[]()</p>\n");

§gfm_quirks: bool

Enables GFM quirks in HTML output which break CommonMark compatibility.

let mut options = Options::default();
let input = "****abcd**** *_foo_*";

assert_eq!(markdown_to_html(input, &options),
           "<p><strong><strong>abcd</strong></strong> <em><em>foo</em></em></p>\n");

options.render.gfm_quirks = true;
assert_eq!(markdown_to_html(input, &options),
           "<p><strong>abcd</strong> <em><em>foo</em></em></p>\n");

§prefer_fenced: bool

Prefer fenced code blocks when outputting CommonMark.

let arena = Arena::new();
let mut options = Options::default();
let input = "```\nhello\n```\n";
let root = parse_document(&arena, input, &options);

let mut buf = Vec::new();
format_commonmark(&root, &options, &mut buf);
assert_eq!(str::from_utf8(&buf).unwrap(), "    hello\n");

buf.clear();
options.render.prefer_fenced = true;
format_commonmark(&root, &options, &mut buf);
assert_eq!(str::from_utf8(&buf).unwrap(), "```\nhello\n```\n");

§figure_with_caption: bool

Render the image as a figure element with the title as its caption.

let mut options = Options::default();
let input = "![image](https://example.com/image.png \"this is an image\")";

assert_eq!(markdown_to_html(input, &options),
           "<p><img src=\"https://example.com/image.png\" alt=\"image\" title=\"this is an image\" /></p>\n");

options.render.figure_with_caption = true;
assert_eq!(markdown_to_html(input, &options),
           "<p><figure><img src=\"https://example.com/image.png\" alt=\"image\" title=\"this is an image\" /><figcaption>this is an image</figcaption></figure></p>\n");

§tasklist_classes: bool

Add classes to the output of the tasklist extension. This allows tasklists to be styled.

let mut options = Options::default();
options.extension.tasklist = true;
let input = "- [ ] Foo";

assert_eq!(markdown_to_html(input, &options),
           "<ul>\n<li><input type=\"checkbox\" disabled=\"\" /> Foo</li>\n</ul>\n");

options.render.tasklist_classes = true;
assert_eq!(markdown_to_html(input, &options),
           "<ul class=\"contains-task-list\">\n<li class=\"task-list-item\"><input type=\"checkbox\" class=\"task-list-item-checkbox\" disabled=\"\" /> Foo</li>\n</ul>\n");

§ol_width: usize

Render ordered list with a minimum marker width. Having a width lower than 3 doesn’t do anything.

let mut options = Options::default();
let input = "1. Something";

assert_eq!(markdown_to_commonmark(input, &options),
           "1. Something\n");

options.render.ol_width = 5;
assert_eq!(markdown_to_commonmark(input, &options),
           "1.   Something\n");