Struct Extension

Fields

strikethrough: bool

Enables the strikethrough extension from the GFM spec.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.strikethrough = true;
assert_eq!(markdown_to_html("Hello ~world~ there.\n", &options),
           "<p>Hello <del>world</del> there.</p>\n");

tagfilter: bool

Enables the tagfilter extension from the GFM spec.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.tagfilter = true;
options.render.r#unsafe = true;
assert_eq!(markdown_to_html("Hello <xmp>.\n\n<xmp>", &options),
           "<p>Hello &lt;xmp>.</p>\n&lt;xmp>\n");

table: bool

Enables the table extension from the GFM spec.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.table = true;
assert_eq!(markdown_to_html("| a | b |\n|---|---|\n| c | d |\n", &options),
           "<table>\n<thead>\n<tr>\n<th>a</th>\n<th>b</th>\n</tr>\n</thead>\n\
            <tbody>\n<tr>\n<td>c</td>\n<td>d</td>\n</tr>\n</tbody>\n</table>\n");

autolink: bool

Enables the autolink extension from the GFM spec.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.autolink = true;
assert_eq!(markdown_to_html("Hello www.github.com.\n", &options),
           "<p>Hello <a href=\"http://www.github.com\">www.github.com</a>.</p>\n");

tasklist: bool

Enables the task list items extension from the GFM spec.

Note that the spec does not define the precise output, so only the bare essentials are rendered.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.tasklist = true;
options.render.r#unsafe = true;
assert_eq!(markdown_to_html("* [x] Done\n* [ ] Not done\n", &options),
           "<ul>\n<li><input type=\"checkbox\" checked=\"\" disabled=\"\" /> Done</li>\n\
           <li><input type=\"checkbox\" disabled=\"\" /> Not done</li>\n</ul>\n");

superscript: bool

Enables the superscript Comrak extension.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.superscript = true;
assert_eq!(markdown_to_html("e = mc^2^.\n", &options),
           "<p>e = mc<sup>2</sup>.</p>\n");

header_id_prefix: Option<String>

Enables the header IDs Comrak extension, with the given ID prefix.

When set, each heading gains an anchor element with an id attribute formed by prefixing the slugified heading text. This is useful for namespacing heading anchors to avoid collisions when rendered Markdown is embedded alongside other content on a page (e.g. GitHub uses the prefix "user-content-" for this purpose).

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.header_id_prefix = Some("user-content-".to_string());
assert_eq!(markdown_to_html("# README\n", &options),
           "<h1 id=\"user-content-readme\">README<a href=\"#readme\" aria-label=\"Link to heading 'README'\" data-heading-content=\"README\" class=\"anchor\"></a></h1>\n");

header_id_prefix_in_href: bool

When enabled alongside header_id_prefix, the header ID prefix is also applied to the href anchor in the generated link.

Has no effect if header_id_prefix is None.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.header_id_prefix = Some("user-content-".to_string());
options.extension.header_id_prefix_in_href = true;
assert_eq!(markdown_to_html("# README\n", &options),
           "<h1 id=\"user-content-readme\">README<a href=\"#user-content-readme\" aria-label=\"Link to heading 'README'\" data-heading-content=\"README\" class=\"anchor\"></a></h1>\n");

footnotes: bool

Enables the footnotes extension per cmark-gfm.

For usage, see src/tests.rs. The extension is modelled after Kramdown.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.footnotes = true;
assert_eq!(markdown_to_html("Hi[^x].\n\n[^x]: A greeting.\n", &options),
           "<p>Hi<sup class=\"footnote-ref\"><a href=\"#fn-x\" id=\"fnref-x\" data-footnote-ref>1</a></sup>.</p>\n<section class=\"footnotes\" data-footnotes>\n<ol>\n<li id=\"fn-x\">\n<p>A greeting. <a href=\"#fnref-x\" class=\"footnote-backref\" data-footnote-backref data-footnote-backref-idx=\"1\" aria-label=\"Back to reference 1\">↩</a></p>\n</li>\n</ol>\n</section>\n");

inline_footnotes: bool

Enables the inline footnotes extension.

Allows inline footnote syntax ^[content] where the content can include inline markup. Inline footnotes are automatically converted to regular footnotes with auto-generated names and share the same numbering sequence.

Requires footnotes to be enabled as well.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.footnotes = true;
options.extension.inline_footnotes = true;
assert_eq!(markdown_to_html("Hi^[An inline note].\n", &options),
           "<p>Hi<sup class=\"footnote-ref\"><a href=\"#fn-__inline_1\" id=\"fnref-__inline_1\" data-footnote-ref>1</a></sup>.</p>\n<section class=\"footnotes\" data-footnotes>\n<ol>\n<li id=\"fn-__inline_1\">\n<p>An inline note <a href=\"#fnref-__inline_1\" class=\"footnote-backref\" data-footnote-backref data-footnote-backref-idx=\"1\" aria-label=\"Back to reference 1\">↩</a></p>\n</li>\n</ol>\n</section>\n");

description_lists: bool

Enables the description lists extension.

Each term must be defined in one paragraph, followed by a blank line, and then by the details. Details begins with a colon.

Not (yet) compatible with render.sourcepos.

First term

: Details for the **first term**

Second term

: Details for the **second term**

    More details in second paragraph.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.description_lists = true;
assert_eq!(markdown_to_html("Term\n\n: Definition", &options),
           "<dl>\n<dt>Term</dt>\n<dd>\n<p>Definition</p>\n</dd>\n</dl>\n");

front_matter_delimiter: Option<String>

Enables the front matter extension.

Front matter, which begins with the delimiter string at the beginning of the file and ends at the end of the next line that contains only the delimiter, is passed through unchanged in markdown output and omitted from HTML output.

---
layout: post
title: Formatting Markdown with Comrak
---

# Shorter Title

etc.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.front_matter_delimiter = Some("---".to_owned());
assert_eq!(
    markdown_to_html("---\nlayout: post\n---\nText\n", &options),
    markdown_to_html("Text\n", &Options::default()));

# use comrak::{format_commonmark, Arena, Options};
use comrak::parse_document;
let mut options = Options::default();
options.extension.front_matter_delimiter = Some("---".to_owned());
let arena = Arena::new();
let input = "---\nlayout: post\n---\nText\n";
let root = parse_document(&arena, input, &options);
let mut buf = String::new();
format_commonmark(&root, &options, &mut buf);
assert_eq!(buf, input);

multiline_block_quotes: bool

Enables the multiline block quote extension.

Place >>> before and after text to make it into a block quote.

Paragraph one

>>>
Paragraph two

- one
- two
>>>

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.multiline_block_quotes = true;
assert_eq!(markdown_to_html(">>>\nparagraph\n>>>", &options),
           "<blockquote>\n<p>paragraph</p>\n</blockquote>\n");

alerts: bool

Enables GitHub style alerts

> [!note]
> Something of note

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.alerts = true;
assert_eq!(markdown_to_html("> [!note]\n> Something of note", &options),
           "<div class=\"markdown-alert markdown-alert-note\">\n<p class=\"markdown-alert-title\">Note</p>\n<p>Something of note</p>\n</div>\n");

math_dollars: bool

Enables math using dollar syntax.

Inline math $1 + 2$ and display math $$x + y$$

$$
x^2
$$

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.math_dollars = true;
assert_eq!(markdown_to_html("$1 + 2$ and $$x = y$$", &options),
           "<p><span data-math-style=\"inline\">1 + 2</span> and <span data-math-style=\"display\">x = y</span></p>\n");
assert_eq!(markdown_to_html("$$\nx^2\n$$\n", &options),
           "<p><span data-math-style=\"display\">\nx^2\n</span></p>\n");

math_latex: bool

Enables math using LaTeX-style delimiters.

Inline math \(1 + 2\) and display math \[x + y\]

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.math_latex = true;
assert_eq!(markdown_to_html("\\(1 + 2\\) and \\[x = y\\]", &options),
           "<p><span data-math-style=\"inline\">1 + 2</span> and <span data-math-style=\"display\">x = y</span></p>\n");

math_code: bool

Enables math using code syntax.

Inline math $`1 + 2`$

```math
x^2
```

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.math_code = true;
assert_eq!(markdown_to_html("$`1 + 2`$", &options),
           "<p><code data-math-style=\"inline\">1 + 2</code></p>\n");
assert_eq!(markdown_to_html("```math\nx^2\n```\n", &options),
           "<pre><code class=\"language-math\" data-math-style=\"display\">x^2\n</code></pre>\n");

wikilinks_title_after_pipe: bool

Enables wikilinks using title after pipe syntax

[[url|link label]]

When both this option and wikilinks_title_before_pipe are enabled, this option takes precedence.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.wikilinks_title_after_pipe = true;
assert_eq!(markdown_to_html("[[url|link label]]", &options),
           "<p><a href=\"url\" data-wikilink=\"true\">link label</a></p>\n");

wikilinks_title_before_pipe: bool

Enables wikilinks using title before pipe syntax

[[link label|url]]

When both this option and wikilinks_title_after_pipe are enabled, wikilinks_title_after_pipe takes precedence.

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.wikilinks_title_before_pipe = true;
assert_eq!(markdown_to_html("[[link label|url]]", &options),
           "<p><a href=\"url\" data-wikilink=\"true\">link label</a></p>\n");

underline: bool

Enables underlines using double underscores

__underlined text__

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.underline = true;

assert_eq!(markdown_to_html("__underlined text__", &options),
           "<p><u>underlined text</u></p>\n");

subscript: bool

Enables subscript text using single tildes.

If the strikethrough option is also enabled, this overrides the single tilde case to output subscript text.

H~2~O

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.subscript = true;

assert_eq!(markdown_to_html("H~2~O", &options),
           "<p>H<sub>2</sub>O</p>\n");

spoiler: bool

Enables spoilers using double vertical bars

Darth Vader is ||Luke's father||

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.spoiler = true;

assert_eq!(markdown_to_html("Darth Vader is ||Luke's father||", &options),
           "<p>Darth Vader is <span class=\"spoiler\">Luke's father</span></p>\n");

greentext: bool

Requires at least one space after a > character to generate a blockquote, and restarts blockquote nesting across unique lines of input

>implying implications

> one
> > two
> three

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.greentext = true;

assert_eq!(markdown_to_html(">implying implications", &options),
           "<p>&gt;implying implications</p>\n");

assert_eq!(markdown_to_html("> one\n> > two\n> three", &options),
           concat!(
            "<blockquote>\n",
            "<p>one</p>\n",
            "<blockquote>\n<p>two</p>\n</blockquote>\n",
            "<p>three</p>\n",
            "</blockquote>\n"));

image_url_rewriter: Option<Arc<dyn URLRewriter + 'c>>

Wraps embedded image URLs using a function or custom trait object.

# use std::sync::Arc;
# use comrak::{markdown_to_html, Options};
let mut options = Options::default();

options.extension.image_url_rewriter = Some(Arc::new(
    |url: &str| format!("https://safe.example.com?url={}", url)
));

assert_eq!(markdown_to_html("![](http://unsafe.example.com/bad.png)", &options),
           "<p><img src=\"https://safe.example.com?url=http://unsafe.example.com/bad.png\" alt=\"\" /></p>\n");

link_url_rewriter: Option<Arc<dyn URLRewriter + 'c>>

Wraps link URLs using a function or custom trait object.

# use std::sync::Arc;
# use comrak::{markdown_to_html, Options};
let mut options = Options::default();

options.extension.link_url_rewriter = Some(Arc::new(
    |url: &str| format!("https://safe.example.com/norefer?url={}", url)
));

assert_eq!(markdown_to_html("[my link](http://unsafe.example.com/bad)", &options),
           "<p><a href=\"https://safe.example.com/norefer?url=http://unsafe.example.com/bad\">my link</a></p>\n");

cjk_friendly_emphasis: bool

Recognizes many emphasis that appear in CJK contexts but are not recognized by plain CommonMark.

**この文は重要です。**但这句话并不重要。

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.cjk_friendly_emphasis = true;

assert_eq!(markdown_to_html("**この文は重要です。**但这句话并不重要。", &options),
           "<p><strong>この文は重要です。</strong>但这句话并不重要。</p>\n");

subtext: bool

Enables block scoped subscript that acts similar to a header.

-# subtext

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.subtext = true;

assert_eq!(markdown_to_html("-# subtext", &options),
          "<p><sub>subtext</sub></p>\n");

highlight: bool

Enables highlighting (mark) using ==.

Hey, ==this is important!==

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.highlight = true;

assert_eq!(markdown_to_html("Hey, ==this is important!==", &options),
          "<p>Hey, <mark>this is important!</mark></p>\n");

insert: bool

Enables inserted text using ++.

This is ++added text++

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.insert = true;

assert_eq!(markdown_to_html("This is ++added text++", &options),
          "<p>This is <ins>added text</ins></p>\n");

block_directive: bool

Enables the container block directive extension.

Container block directives are container blocks that start and end with :::. The info string after the opening ::: is used as the block type.

:::warning
A paragraph.

- item one
- item two
:::

# use comrak::{markdown_to_html, Options};
let mut options = Options::default();
options.extension.block_directive = true;

assert_eq!(markdown_to_html(":::warning\nparagraph\n:::", &options),
           "<div class=\"warning\">\n<p>paragraph</p>\n</div>\n");