API Reference

AdmonitionRule()

Parse admonition blocks (notes, warnings, tips, etc.).

Not enabled by default. Uses !!! syntax with a category and optional title.

!!! note "Custom Title"
    This is an admonition block.
    It can contain multiple paragraphs.

!!! warning
    Default title is the category name.

AsteriskEmphasisRule()

Parse emphasis using asterisks (* and **).

Enabled by default. Single for italic, double for bold.

*italic* and **bold** and ***both***

AttributeRule()

Parse attribute syntax to attach metadata to elements.

Not enabled by default. Uses {#id .class key=value} syntax after elements.

# Heading {#custom-id .highlight}

Paragraph with attributes.
{.note}

[Link](url){target=_blank}

AtxHeadingRule()

Parse ATX-style headings (# Heading).

Enabled by default. Supports levels 1-6 with corresponding number of # characters.

# Heading 1
## Heading 2
### Heading 3

AutoIdentifierRule()

Automatically generate IDs for headings.

Not enabled by default. IDs are slugified from heading text. Duplicate IDs get numeric suffixes. Headings with explicit IDs (via AttributeRule) are preserved.

# My Heading        → <h1 id="my-heading">
# My Heading        → <h1 id="my-heading-1"> (duplicate)
# Custom {#my-id}   → <h1 id="my-id"> (with AttributeRule)

AutolinkRule()

Parse autolinks (<url> and <email@example.com>).

Enabled by default. URLs must include a scheme.

<https://example.com>
<user@example.com>

BlockQuoteRule()

Parse block quotes (> quoted text).

Enabled by default. Block quotes can be nested and contain other block elements.

> This is a block quote.
>
> > Nested quote.

CitationRule()

Parse citation references using @key or [@key] syntax.

Not enabled by default. Citations can be bare (@smith2020) or bracketed ([@smith2020]). Requires a bibliography to be configured for rendering.

According to @smith2020, this is true.

Multiple citations: [@smith2020; @jones2021]

DollarMathRule()

Parse LaTeX math with dollar sign delimiters (without backticks).

Not enabled by default. Inline math uses $...$, display math uses $$...$$.

Inline: $E = mc^2$

Display:
$$
\int_0^\infty e^{-x^2} dx
$$

FencedCodeBlockRule()

Parse fenced code blocks (triple backticks or tildes).

Enabled by default. Supports optional language identifier.

```julia
println("Hello")
```

FencedDivRule()

Parse Pandoc-style fenced divs (::: class blocks).

Not enabled by default. Creates generic container elements with CSS classes. Divs can be nested by using more colons.

::: warning
This is a warning div.
:::

:::: outer
::: inner
Nested divs.
:::
::::

FootnoteRule()

Parse footnote definitions and references.

Not enabled by default. Define footnotes with [^id]: and reference with [^id].

Here is a footnote reference[^1].

[^1]: This is the footnote content.

FrontMatterRule(; yaml=identity, toml=identity, json=identity)

Parse YAML, TOML, or JSON front matter at document start.

Not enabled by default. Front matter is delimited by --- (YAML), +++ (TOML), or ;;; (JSON). Pass parser functions for each format.

---
title: My Document
author: Jane Doe
---

Document content here.

Use frontmatter to extract the parsed data.

GitHubAlertRule()

Parse GitHub-style alert blockquotes.

Not enabled by default. Converts blockquotes starting with [!TYPE] into styled alert boxes. Supported types: NOTE, TIP, IMPORTANT, WARNING, CAUTION.

> [!NOTE]
> This is a note alert.

> [!WARNING]
> This is a warning alert.

HtmlBlockRule()

Parse raw HTML blocks.

Enabled by default. Recognizes common HTML tags and passes them through unchanged.

<div class="warning">
  <p>Raw HTML content</p>
</div>

HtmlEntityRule()

Parse HTML entities (&, {, {).

Enabled by default. Converts entities to their Unicode equivalents.

© & < <

HtmlInlineRule()

Parse inline HTML tags.

Enabled by default. Passes through raw HTML tags unchanged.

This has <em>inline HTML</em> tags.

ImageRule()

Parse inline and reference images.

Enabled by default. Same syntax as links but prefixed with !.

![alt text](image.png)
![alt text][ref]

[ref]: image.png

IndentedCodeBlockRule()

Parse indented code blocks (4 spaces or 1 tab).

Enabled by default.

    code here
    more code

InlineCodeRule()

Parse inline code spans (backtick-delimited).

Enabled by default. Uses matching backtick counts for nesting.

Use `code` inline or `` `backticks` `` inside.

LinkRule()

Parse inline and reference links.

Enabled by default. Supports both inline [text](url) and reference [text][ref] styles.

[inline link](https://example.com)
[reference link][ref]

[ref]: https://example.com

ListItemRule()

Parse list items (bulleted and ordered lists).

Enabled by default. Supports -, +, * for bullets and 1., 1) for ordered.

- Item one
- Item two

1. First
2. Second

MathRule()

Parse LaTeX math in double-backtick code spans and fenced code blocks.

Not enabled by default. Inline math uses double backticks (``...``), display math uses math ``` fenced blocks.

Inline: ``E = mc^2``

Display:
```math
\int_0^\infty e^{-x^2} dx
```

Parser()

Create a CommonMark parser with default block and inline rules enabled.

The parser can be called directly on a string to produce an AST, which can then be rendered to various output formats using html, latex, term, markdown, notebook, or typst.

Examples

p = Parser()
ast = p("# Hello\n\nWorld")
html(ast)  # "<h1>Hello</h1>\n<p>World</p>\n"

Use enable! and disable! to customize which rules are active.

p = Parser()
enable!(p, TableRule())

RawContentRule(; formats...)

Parse format-specific raw content blocks.

Not enabled by default. Uses $`content`{=format}$ syntax for inline and fenced blocks with {=format} for blocks. The _inline or _block suffix is added automatically based on context.

`<span>html</span>`{=html}

{=latex} \textbf{LaTeX content}

Default formats: html, latex, typst.

ReferenceLinkRule()

Preserve reference link style in the AST.

Not enabled by default. By default, reference links are resolved to inline links during parsing. This rule preserves the original reference style (full, collapsed, or shortcut) for roundtrip rendering.

[full style][ref]
[collapsed style][]
[shortcut style]

[ref]: https://example.com

SetextHeadingRule()

Parse setext-style headings (underlined with = or -).

Enabled by default. Only supports levels 1 and 2.

Heading 1
=========

Heading 2
---------

StrikethroughRule()

Parse strikethrough text (~~deleted~~).

Not enabled by default. Uses double tildes to mark deleted text.

~~This text is struck through.~~

SubscriptRule()

Parse subscript text (~subscript~).

Not enabled by default. Uses single tildes to mark subscript text.

H~2~O renders as H₂O

SuperscriptRule()

Parse superscript text (^superscript^).

Not enabled by default. Uses carets to mark superscript text.

x^2^ renders as x²

TableRule()

Parse GitHub Flavored Markdown pipe tables.

Not enabled by default. Tables use | to separate columns and require a header separator row.

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Alignment can be specified with : in the separator row:

• :--- left align
• :---: center align
• ---: right align

TaskListRule()

Parse GitHub-style task list items.

Not enabled by default. Converts list items starting with [ ] or [x] into interactive checkboxes in HTML output.

- [ ] Unchecked item
- [x] Checked item
- Regular item

ThematicBreakRule()

Parse thematic breaks (horizontal rules).

Enabled by default. Requires 3+ of *, -, or _ characters.

***

---

___

TypographyRule(; double_quotes=true, single_quotes=true, ellipses=true, dashes=true)

Convert ASCII punctuation to typographic equivalents.

Not enabled by default. Converts:

• "..." to "..." (curly double quotes)
• '...' to '...' (curly single quotes)
• ... to … (ellipsis)
• -- to – and --- to — (en/em dashes)

Disable specific conversions with keyword arguments.

UnderscoreEmphasisRule()

Parse emphasis using underscores (_ and __).

Enabled by default. Single for italic, double for bold.

_italic_ and __bold__ and ___both___

ast_equal(a::Node, b::Node)

Compare two AST nodes for structural equality. Ignores source positions and parser state, comparing only the semantic content: container types, literals, and tree structure.

Given the current indent of the renderer we check to see how much space is left on the current line.

container_equal(a::AbstractContainer, b::AbstractContainer)

Compare two container types for equality, checking type and all fields.

disable!(parser, rule)
disable!(parser, rules)

Disable a parsing rule or collection of rules from the parser.

This removes the specified rules and re-enables all remaining rules. Useful for removing default CommonMark behavior.

Returns the parser for method chaining.

Examples

p = Parser()
disable!(p, SetextHeadingRule())  # Only allow ATX-style headings
disable!(p, [HtmlBlockRule(), HtmlInlineRule()])  # Disable raw HTML

See also: enable!, Parser

enable!(parser, rule)
enable!(parser, rules)

Enable a parsing rule or collection of rules in the parser.

Rules can be core CommonMark rules (e.g., AtxHeadingRule) or extension rules (e.g., TableRule, AdmonitionRule).

Returns the parser for method chaining.

Examples

p = Parser()
enable!(p, TableRule())
enable!(p, [FootnoteRule(), AdmonitionRule()])

See also: disable!, Parser

Finalize literal from buffer, converting IOBuffer to String.

frontmatter(ast::Node) -> Dict{String,Any}

Extract front matter data from a parsed document.

Returns an empty dictionary if no front matter is present. Requires FrontMatterRule to be enabled during parsing. Supports YAML (---), TOML (+++), and JSON (;;;) delimiters.

Examples

p = Parser()
enable!(p, FrontMatterRule(yaml=YAML.load))
ast = p("""
---
title: My Document
author: Jane Doe
---
# Content
""")
frontmatter(ast)  # Dict("title" => "My Document", "author" => "Jane Doe")

Get meta value without allocating if meta is nothing.

Check if meta has key without allocating if meta is nothing.

html(ast::Node) -> String
html(filename::String, ast::Node)
html(io::IO, ast::Node)

Render a CommonMark AST to HTML.

Keyword Arguments

• softbreak::String = "\n": String to use for soft line breaks
• safe::Bool = false: Escape potentially unsafe HTML content
• sourcepos::Bool = false: Include source position data attributes

Examples

p = Parser()
ast = p("# Hello\n\nWorld")
html(ast)  # "<h1>Hello</h1>\n<p>World</p>\n"

latex(ast::Node) -> String
latex(filename::String, ast::Node)
latex(io::IO, ast::Node)

Render a CommonMark AST to LaTeX.

Examples

p = Parser()
ast = p("# Hello\n\nWorld")
latex(ast)  # "\\section{Hello}\n\nWorld\n"

What is the width of the literal text stored in node and all of it's child nodes. Used to determine alignment for rendering nodes such as centered.

markdown(ast::Node) -> String
markdown(filename::String, ast::Node)
markdown(io::IO, ast::Node)

Render a CommonMark AST back to Markdown text.

Useful for normalizing Markdown formatting or for roundtrip testing. Output uses opinionated formatting with no trailing whitespace.

Examples

p = Parser()
ast = p("# Hello\n\nWorld")
markdown(ast)  # "# Hello\n\nWorld\n"

Merge dict into meta, initializing if needed.

notebook(ast::Node) -> String
notebook(filename::String, ast::Node)
notebook(io::IO, ast::Node)

Render a CommonMark AST to a Jupyter notebook (.ipynb format).

Code blocks are converted to code cells, and other content becomes Markdown cells.

Examples

p = Parser()
ast = p("# Title\n\n```julia\nprintln(\"Hello\")\n```")
notebook("output.ipynb", ast)

Literal printing of a of parts. Behaviour depends on when .wrap is active at the moment, which is set in Paragraph rendering.

Print out all the current segments present in the margin buffer.

Each time a segment gets printed it's count is reduced. When a segment has a count of zero it won't be printed and instead spaces equal to it's width are printed. For persistent printing a count of -1 should be used.

Adds a new segment to the margin buffer. This segment is persistent and thus will print on every margin print.

Adds a new segment to the margin buffer, but will only print out for the given number of count calls to print_margin. After count calls it will instead print out spaces equal to the width of text.

Adds new segmant to the margin buffer. count determines how many time initial is printed. After that, the width of rest is printed instead.

Set meta value, initializing dict if needed.

term(ast::Node) -> String
term(filename::String, ast::Node)
term(io::IO, ast::Node)

Render a CommonMark AST for terminal display with ANSI formatting.

Includes colored syntax highlighting for code blocks when a highlighter is configured.

Examples

p = Parser()
ast = p("# Hello\n\n**World**")
term(ast)  # Returns ANSI-formatted string

typst(ast::Node) -> String
typst(filename::String, ast::Node)
typst(io::IO, ast::Node)

Render a CommonMark AST to Typst markup.

Examples

p = Parser()
ast = p("# Hello\n\nWorld")
typst(ast)

cm""

A string macro for markdown text that implements standard string interpolation. Returns a parsed markdown AST with the values of the interpolation expressions embedded in the AST.

value = "interpolated"
cm"Some *$(value)* text."

The default syntax rules used for parsing are:

• AdmonitionRule
• AttributeRule
• AutoIdentifierRule
• CitationRule
• FootnoteRule
• MathRule
• RawContentRule
• TableRule
• TypographyRule

which matches closely with the default syntax supported in Markdown.@md_str.

A custom Parser can be invoked when using cm"" by providing a suffix to the macro call, for example:

more = "more"
cm"Some **$(uppercase(more))** text."none

where the suffixed none will invoke a basic Parser with no additional syntax rules enabled!. To use your own custom parser, for example to only enable the TypographyRule, you can suffix the call with a named function from the current module's global scope that returns the Parser object with the required rules enabled:

custom() = enable!(Parser(), TypographyRule())

It can then be used as

str = "custom"
cm"A '$(titlecase(str))' parser..."custom