@spec anchorize(String.t()) :: String.t()

Converts text to a heading anchor.

Examples

iex> MDExNative.Comrak.anchorize("Hello World")
"hello-world"

@spec dangerous_url?(String.t()) :: boolean()

Returns whether a URL is considered dangerous or not.

Calls comrak::html::dangerous_url/1.

Examples

iex> MDExNative.Comrak.dangerous_url?("javascript:alert(1)")
true

iex> MDExNative.Comrak.dangerous_url?("https://elixir-lang.org")
false

iex> MDExNative.Comrak.dangerous_url?("data:image/png;base64,AAAA")
false

@spec document_to_commonmark(MDExNative.Comrak.Document.t(), options()) ::
  {:ok, markdown()} | {:error, Exception.t()}

Converts a generic MDExNative.Comrak document to CommonMark.

@spec document_to_commonmark!(MDExNative.Comrak.Document.t(), options()) :: markdown()

Same as document_to_commonmark/2 but raises the error instead of returning it.

@spec document_to_html(MDExNative.Comrak.Document.t(), options()) ::
  {:ok, html()} | {:error, Exception.t()}

Converts a generic MDExNative.Comrak document to HTML.

@spec document_to_html!(MDExNative.Comrak.Document.t(), options()) :: html()

Same as document_to_html/2 but raises the error instead of returning it.

@spec document_to_xml(MDExNative.Comrak.Document.t(), options()) ::
  {:ok, xml()} | {:error, Exception.t()}

Converts a generic MDExNative.Comrak document to XML.

@spec document_to_xml!(MDExNative.Comrak.Document.t(), options()) :: xml()

Same as document_to_xml/2 but raises the error instead of returning it.

@spec markdown_to_html(markdown(), options()) ::
  {:ok, html()} | {:error, Exception.t()}

Converts Markdown to HTML.

Options

Pass Comrak options as keyword lists matching comrak::Options or the extra :syntax_highlight and :sanitize options: MDExNative adds two top-level options:

• :extension - maps to Comrak's Extension options.

• :parse - maps to Comrak's Parse options.

• :render - maps to Comrak's Render options,

• :syntax_highlight - highlights fenced code blocks. Disabled by default.

  Defaults to syntax_highlight: nil.

  To highlight code, compile MDExNative with a highlighter and choose the engine:

  Lumis

    config :mdex_native, syntax_highlighter: :lumis
  
    [engine: :lumis, opts: [formatter: {:html_inline, theme: "catppuccin_macchiato"}]]

  Syntect

    config :mdex_native, syntax_highlighter: :syntect
  
    [engine: :syntect, opts: [theme: "Catppuccin Macchiato"]]

  See the Syntax highlighting guide for complete examples.

• :sanitize - cleans rendered HTML. Defaults to nil.

  See the Sanitization guide for more info.

• :budget - bounds parsing, as [parse_time: milliseconds, parse_memory: bytes]. :parse_memory caps the heap the parse holds. 0 or nil means no limit.

Examples

iex> MDExNative.Comrak.markdown_to_html("**bold**")
{:ok, "<p><strong>bold</strong></p>\n"}

iex> MDExNative.Comrak.markdown_to_html("- [x] done", extension: [tasklist: true])
{:ok, "<ul>\n<li><input type=\"checkbox\" checked=\"\" disabled=\"\" /> done</li>\n</ul>\n"}

iex> MDExNative.Comrak.markdown_to_html("<h1>Title</h1><p>Content</p>", render: [unsafe: true], sanitize: [rm_tags: ["h1"]])
{:ok, "Title<p>Content</p>\n"}

# default disabled syntax highlighter
iex> markdown = "```rust\nfn main() {}\n```"
iex> MDExNative.Comrak.markdown_to_html(markdown)
{:ok, "<pre><code class=\"language-rust\">fn main() {}\n</code></pre>\n"}

@spec markdown_to_html!(markdown(), options()) :: html()

Same as markdown_to_html/2 but raises the error instead of returning it.

@spec markdown_to_xml(markdown(), options()) :: {:ok, xml()} | {:error, Exception.t()}

Converts Markdown to XML.

Examples

iex> MDExNative.Comrak.markdown_to_xml("# Hello")
{:ok, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE document SYSTEM \"CommonMark.dtd\">\n<document xmlns=\"http://commonmark.org/xml/1.0\">\n  <heading level=\"1\">\n    <text xml:space=\"preserve\">Hello</text>\n  </heading>\n</document>\n"}

iex> MDExNative.Comrak.markdown_to_xml("# Hello", render: [sourcepos: true])
{:ok, "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<!DOCTYPE document SYSTEM \"CommonMark.dtd\">\n<document sourcepos=\"1:1-1:7\" xmlns=\"http://commonmark.org/xml/1.0\">\n  <heading sourcepos=\"1:1-1:7\" level=\"1\">\n    <text sourcepos=\"1:3-1:7\" xml:space=\"preserve\">Hello</text>\n  </heading>\n</document>\n"}

@spec markdown_to_xml!(markdown(), options()) :: xml()

Same as markdown_to_xml/2 but raises the error instead of returning it.

@spec parse_code_fence_info(String.t() | nil) :: code_fence_info()

Parses a fenced code block info string into generic parts.

The first word is returned as the language, the remaining text is preserved as metadata, and shell-like tokens in the metadata are exposed as attributes.

Examples

iex> MDExNative.Comrak.parse_code_fence_info(~s(elixir pre_class="demo" highlight_lines=2 include_highlights))
%{
  language: "elixir",
  metadata: ~s(pre_class="demo" highlight_lines=2 include_highlights),
  attributes: %{
    "pre_class" => "demo",
    "highlight_lines" => "2",
    "include_highlights" => true
  }
}

iex> MDExNative.Comrak.parse_code_fence_info("")
%{language: "", metadata: "", attributes: %{}}

@spec parse_document(markdown(), options()) ::
  {:ok, MDExNative.Comrak.Document.t()} | {:error, Exception.t()}

Parses Markdown into a generic MDExNative.Comrak AST.

Examples

iex> MDExNative.Comrak.parse_document("# Hello")
{:ok,
 %MDExNative.Comrak.Document{
   nodes: [
     %MDExNative.Comrak.Heading{
       nodes: [
         %MDExNative.Comrak.Text{literal: "Hello", sourcepos: %MDExNative.Comrak.Sourcepos{start: {1, 3}, end: {1, 7}}}
       ],
       level: 1,
       setext: false,
       sourcepos: %MDExNative.Comrak.Sourcepos{start: {1, 1}, end: {1, 7}}
     }
   ],
   sourcepos: %MDExNative.Comrak.Sourcepos{start: {1, 1}, end: {1, 7}}
 }}

@spec parse_document!(markdown(), options()) :: MDExNative.Comrak.Document.t()

Same as parse_document/2 but raises the error instead of returning it.