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

Converts a given text string to a format that can be used as an "anchor", such as in a Table of Contents.

This uses the same algorithm GFM uses for anchor ids, so it can be used reliably.

Repeated anchors

GFM will dedupe multiple repeated anchors with the same value by appending an incrementing number to the end of the anchor. That is beyond the scope of this function, so you will have to handle it yourself.

Examples

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

iex> MDEx.anchorize("Hello, World!")
"hello-world"

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

iex> MDEx.anchorize("Hello World 123")
"hello-world-123"

iex> MDEx.anchorize("你好世界")
"你好世界"

@spec default_extension_options() :: extension_options()

Returns the default options for the :extension group.

@spec default_parse_options() :: parse_options()

Returns the default options for the :parse group.

@spec default_render_options() :: render_options()

Returns the default options for the :render group.

@spec default_sanitize_options() :: sanitize_options()

Returns the default options for the :sanitize group.

@spec default_syntax_highlight_options() :: syntax_highlight_options()

Returns the default options for the :syntax_highlight group.

@spec new(options()) :: MDEx.Pipe.t()

Builds a new MDEx.Pipe instance.

Once the pipe is complete, call either one of the following functions to format the document:

• MDEx.to_html/2
• MDEx.to_json/1
• MDEx.to_xml/2
• MDEx.to_markdown/1

Examples

• Build a pipe with :document:

  iex> mdex = MDEx.new(document: "# Hello")
  iex> MDEx.to_html(mdex)
  {:ok, "<h1>Hello</h1>"}
  
  iex> mdex = MDEx.new(document: "Hello ~world~", extension: [strikethrough: true])
  iex> MDEx.to_json(mdex)
  {:ok, ~s|{"nodes":[{"nodes":[{"literal":"Hello ","node_type":"MDEx.Text"},{"nodes":[{"literal":"world","node_type":"MDEx.Text"}],"node_type":"MDEx.Strikethrough"}],"node_type":"MDEx.Paragraph"}],"node_type":"MDEx.Document"}|}

• Pass a :document when formatting:

  iex> mdex = MDEx.new(extension: [strikethrough: true])
  iex> MDEx.to_xml(mdex, document: "Hello ~world~")
  {:ok, ~s|<?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document SYSTEM "CommonMark.dtd">
  <document xmlns="http://commonmark.org/xml/1.0">
    <paragraph>
      <text xml:space="preserve">Hello </text>
      <strikethrough>
        <text xml:space="preserve">world</text>
      </strikethrough>
    </paragraph>
  </document>|}

Notes

1. Source :document is automatically parsed into MDEx.Document before the pipeline runs so every step receives the same data type.

2. You can pass the document when creating the pipe:

MDEx.new(document: "# Hello") |> MDEx.to_html()

Or pass it only when formatting the document, useful to reuse the same pipe with different documents and formats.

mdex = MDEx.new()
# ... attach plugins and steps

MDEx.to_html(mdex, document: "# Hello HTML")
MDEx.to_json(mdex, document: "# Hello JSON")

@spec parse_document(markdown :: String.t() | {:json, String.t()}, options()) ::
  {:ok, MDEx.Document.t()} | {:error, any()}

Parse source and returns MDEx.Document.

Source can be either a Markdown string or a tagged JSON string.

Examples

• Parse Markdown with default options:

  iex> MDEx.parse_document!("""
  ...> # Languages
  ...>
  ...> - Elixir
  ...> - Rust
  ...> """)
  %MDEx.Document{
    nodes: [
      %MDEx.Heading{nodes: [%MDEx.Text{literal: "Languages"}], level: 1, setext: false},
      %MDEx.List{
        nodes: [
          %MDEx.ListItem{
            nodes: [%MDEx.Paragraph{nodes: [%MDEx.Text{literal: "Elixir"}]}],
            list_type: :bullet,
            marker_offset: 0,
            padding: 2,
            start: 1,
            delimiter: :period,
            bullet_char: "-",
            tight: false
          },
          %MDEx.ListItem{
            nodes: [%MDEx.Paragraph{nodes: [%MDEx.Text{literal: "Rust"}]}],
            list_type: :bullet,
            marker_offset: 0,
            padding: 2,
            start: 1,
            delimiter: :period,
            bullet_char: "-",
            tight: false
          }
        ],
        list_type: :bullet,
        marker_offset: 0,
        padding: 2,
        start: 1,
        delimiter: :period,
        bullet_char: "-",
        tight: true
      }
    ]
  }

• Parse Markdown with custom options:

  iex> MDEx.parse_document!("Darth Vader is ||Luke's father||", extension: [spoiler: true])
  %MDEx.Document{
    nodes: [
      %MDEx.Paragraph{
        nodes: [
          %MDEx.Text{literal: "Darth Vader is "},
          %MDEx.SpoileredText{nodes: [%MDEx.Text{literal: "Luke's father"}]}
        ]
      }
    ]
  }

• Parse JSON:

  iex> json = ~s|{"nodes":[{"nodes":[{"literal":"Title","node_type":"MDEx.Text"}],"level":1,"setext":false,"node_type":"MDEx.Heading"}],"node_type":"MDEx.Document"}|
  iex> MDEx.parse_document!({:json, json})
  %MDEx.Document{
    nodes: [
      %MDEx.Heading{
        nodes: [%MDEx.Text{literal: "Title"} ],
        level: 1,
        setext: false
      }
    ]
  }

@spec parse_document!(markdown :: String.t() | {:json, String.t()}, options()) ::
  MDEx.Document.t()

Same as parse_document/2 but raises if the parsing fails.

@spec parse_fragment(String.t(), options()) :: {:ok, MDEx.Document.md_node()} | nil

Parse a markdown string and returns only the node that represents the fragment.

Usually that means filtering out the parent document and paragraphs.

That's useful to generate fragment nodes and inject them into the document when you're manipulating it.

Use parse_document/2 to generate a complete document.

Examples

iex> MDEx.parse_fragment("# Elixir")
{:ok, %MDEx.Heading{nodes: [%MDEx.Text{literal: "Elixir"}], level: 1, setext: false}}

iex> MDEx.parse_fragment("<h1>Elixir</h1>")
{:ok, %MDEx.HtmlBlock{nodes: [], block_type: 6, literal: "<h1>Elixir</h1>\n"}}

@spec parse_fragment!(String.t(), options()) :: MDEx.Document.md_node()

Same as parse_fragment/2 but raises if the parsing fails or returns nil.

@spec safe_html(
  String.t(),
  options :: [sanitize: sanitize_options() | nil, escape: [atom()]]
) :: String.t()

Utility function to sanitize and escape HTML.

Examples

iex> MDEx.safe_html("<script>console.log('attack')</script>")
""

iex> MDEx.safe_html("<custom_tag>Hello</custom_tag>")
"Hello"

iex> MDEx.safe_html("<custom_tag>Hello</custom_tag>", sanitize: [add_tags: ["custom_tag"]], escape: [content: false])
"<custom_tag>Hello</custom_tag>"

iex> MDEx.safe_html("<h1>{'Example:'}</h1><code>{:ok, 'MDEx'}</code>")
"&lt;h1&gt;{&#x27;Example:&#x27;}&lt;&#x2f;h1&gt;&lt;code&gt;&lbrace;:ok, &#x27;MDEx&#x27;&rbrace;&lt;&#x2f;code&gt;"

iex> MDEx.safe_html("<h1>{'Example:'}</h1><code>{:ok, 'MDEx'}</code>", escape: [content: false])
"<h1>{'Example:'}</h1><code>&lbrace;:ok, 'MDEx'&rbrace;</code>"

Options

• :sanitize - cleans HTML after rendering. Defaults to MDEx.default_sanitize_options/0.

  • keyword - sanitize_options/0
  • nil - do not sanitize output.

• :escape - which entities should be escaped. Defaults to [:content, :curly_braces_in_code].

  • :content - escape common chars like <, >, &, and others in the HTML content;
  • :curly_braces_in_code - escape { and } only inside <code> tags, particularly useful for compiling HTML in LiveView;

@spec to_html(source(), options()) ::
  {:ok, String.t()}
  | {:error, MDEx.DecodeError.t()}
  | {:error, MDEx.InvalidInputError.t()}

Convert Markdown, MDEx.Document, or MDEx.Pipe to HTML.

Examples

iex> MDEx.to_html("# MDEx")
{:ok, "<h1>MDEx</h1>"}

iex> MDEx.to_html("Implemented with:\n1. Elixir\n2. Rust")
{:ok, "<p>Implemented with:</p>\n<ol>\n<li>Elixir</li>\n<li>Rust</li>\n</ol>"}

iex> MDEx.to_html(%MDEx.Document{nodes: [%MDEx.Heading{nodes: [%MDEx.Text{literal: "MDEx"}], level: 3, setext: false}]})
{:ok, "<h3>MDEx</h3>"}

iex> MDEx.to_html("Hello ~world~ there", extension: [strikethrough: true])
{:ok, "<p>Hello <del>world</del> there</p>"}

iex> MDEx.to_html("<marquee>visit https://beaconcms.org</marquee>", extension: [autolink: true], render: [unsafe: true])
{:ok, "<p><marquee>visit <a href=\"https://beaconcms.org\">https://beaconcms.org</a></marquee></p>"}

Fragments of a document are also supported:

iex> MDEx.to_html(%MDEx.Paragraph{nodes: [%MDEx.Text{literal: "MDEx"}]})
{:ok, "<p>MDEx</p>"}

@spec to_html!(source(), options()) :: String.t()

Same as to_html/2 but raises error if the conversion fails.

@spec to_json(source()) ::
  {:ok, String.t()}
  | {:error, MDEx.DecodeError.t()}
  | {:error, MDEx.InvalidInputError.t()}

Convert Markdown, MDEx.Document, or MDEx.Pipe to JSON using default options.

Use to_json/2 to pass custom options.

Examples

iex> MDEx.to_json("# Hello")
{:ok, ~s|{"nodes":[{"nodes":[{"literal":"Hello","node_type":"MDEx.Text"}],"level":1,"setext":false,"node_type":"MDEx.Heading"}],"node_type":"MDEx.Document"}|}

iex> MDEx.to_json("1. First\n2. Second")
{:ok, ~s|{"nodes":[{"start":1,"nodes":[{"start":1,"nodes":[{"nodes":[{"literal":"First","node_type":"MDEx.Text"}],"node_type":"MDEx.Paragraph"}],"delimiter":"period","padding":3,"list_type":"ordered","marker_offset":0,"bullet_char":"","tight":false,"is_task_list":false,"node_type":"MDEx.ListItem"},{"start":2,"nodes":[{"nodes":[{"literal":"Second","node_type":"MDEx.Text"}],"node_type":"MDEx.Paragraph"}],"delimiter":"period","padding":3,"list_type":"ordered","marker_offset":0,"bullet_char":"","tight":false,"is_task_list":false,"node_type":"MDEx.ListItem"}],"delimiter":"period","padding":3,"list_type":"ordered","marker_offset":0,"bullet_char":"","tight":true,"is_task_list":false,"node_type":"MDEx.List"}],"node_type":"MDEx.Document"}|}

iex> MDEx.to_json(%MDEx.Document{nodes: [%MDEx.Heading{nodes: [%MDEx.Text{literal: "Hello"}], level: 3, setext: false}]})
{:ok, ~s|{"nodes":[{"nodes":[{"literal":"Hello","node_type":"MDEx.Text"}],"level":3,"setext":false,"node_type":"MDEx.Heading"}],"node_type":"MDEx.Document"}|}

Fragments of a document are also supported:

iex> MDEx.to_json(%MDEx.Paragraph{nodes: [%MDEx.Text{literal: "Hello"}]})
{:ok, ~s|{"nodes":[{"nodes":[{"literal":"Hello","node_type":"MDEx.Text"}],"node_type":"MDEx.Paragraph"}],"node_type":"MDEx.Document"}|}

@spec to_json(source(), options()) ::
  {:ok, String.t()}
  | {:error, MDEx.DecodeError.t()}
  | {:error, MDEx.InvalidInputError.t()}

Convert Markdown, MDEx.Document, or MDEx.Pipe to JSON using custom options.

Examples

iex> MDEx.to_json("Hello ~world~", extension: [strikethrough: true])
{:ok, ~s|{"nodes":[{"nodes":[{"literal":"Hello ","node_type":"MDEx.Text"},{"nodes":[{"literal":"world","node_type":"MDEx.Text"}],"node_type":"MDEx.Strikethrough"}],"node_type":"MDEx.Paragraph"}],"node_type":"MDEx.Document"}|}

@spec to_json!(source()) :: String.t()

Same as to_json/1 but raises an error if the conversion fails.

@spec to_json!(source(), options()) :: String.t()

Same as to_json/2 but raises error if the conversion fails.

@spec to_markdown(MDEx.Document.t() | MDEx.Pipe.t()) ::
  {:ok, String.t()} | {:error, MDEx.DecodeError.t()}

Convert MDEx.Document or MDEx.Pipe to Markdown using default options.

Use to_markdown/2 to pass custom options.

Example

iex> MDEx.to_markdown(%MDEx.Document{nodes: [%MDEx.Heading{nodes: [%MDEx.Text{literal: "Hello"}], level: 3, setext: false}]})
{:ok, "### Hello"}

@spec to_markdown(MDEx.Document.t() | MDEx.Pipe.t(), options()) ::
  {:ok, String.t()} | {:error, MDEx.DecodeError.t()}

Convert MDEx.Document or MDEx.Pipe to Markdown using custom options.

@spec to_markdown!(MDEx.Document.t()) :: String.t()

Same as to_markdown/1 but raises MDEx.DecodeError if the conversion fails.

@spec to_markdown!(MDEx.Document.t(), options()) :: String.t()

Same as to_markdown/2 but raises MDEx.DecodeError if the conversion fails.

@spec to_xml(source(), options()) ::
  {:ok, String.t()}
  | {:error, MDEx.DecodeError.t()}
  | {:error, MDEx.InvalidInputError.t()}

Convert Markdown, MDEx.Document, or MDEx.Pipe to XML.

Examples

iex> {:ok, xml} = MDEx.to_xml("Hello ~world~ there", extension: [strikethrough: true])
iex> xml
~s|<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "CommonMark.dtd">
<document xmlns="http://commonmark.org/xml/1.0">
  <paragraph>
    <text xml:space="preserve">Hello </text>
    <strikethrough>
      <text xml:space="preserve">world</text>
    </strikethrough>
    <text xml:space="preserve"> there</text>
  </paragraph>
</document>|

iex> {:ok, xml} = MDEx.to_xml("<marquee>visit https://beaconcms.org</marquee>", extension: [autolink: true], render: [unsafe: true])
iex> xml
~s|<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "CommonMark.dtd">
<document xmlns="http://commonmark.org/xml/1.0">
  <paragraph>
    <html_inline xml:space="preserve">&lt;marquee&gt;</html_inline>
    <text xml:space="preserve">visit </text>
    <link destination="https://beaconcms.org" title="">
      <text xml:space="preserve">https://beaconcms.org</text>
    </link>
    <html_inline xml:space="preserve">&lt;/marquee&gt;</html_inline>
  </paragraph>
</document>|

Fragments of a document are also supported:

iex> {:ok, xml} = MDEx.to_xml(%MDEx.Paragraph{nodes: [%MDEx.Text{literal: "MDEx"}]})
iex> xml
~s|<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "CommonMark.dtd">
<document xmlns="http://commonmark.org/xml/1.0">
  <paragraph>
    <text xml:space="preserve">MDEx</text>
  </paragraph>
</document>|

@spec to_xml!(source(), options()) :: String.t()

Same as to_xml/2 but raises error if the conversion fails.

@spec traverse_and_update(MDEx.Document.t(), (MDEx.Document.md_node() ->
                                          MDEx.Document.md_node())) ::
  MDEx.Document.t()

Low-level function to traverse and update the Markdown document preserving the tree structure format.

See MDEx.Document for more information about the tree structure and for higher-level functions using the Access and Enumerable protocols.

Examples

Traverse an entire Markdown document:

iex> import MDEx.Sigil
iex> doc = ~MD"""
...> # Languages
...>
...> `elixir`
...>
...> `rust`
...> """
iex> MDEx.traverse_and_update(doc, fn
...>   %MDEx.Code{literal: "elixir"} = node -> %{node | literal: "ex"}
...>   %MDEx.Code{literal: "rust"} = node -> %{node | literal: "rs"}
...>   node -> node
...> end)
%MDEx.Document{
  nodes: [
    %MDEx.Heading{nodes: [%MDEx.Text{literal: "Languages"}], level: 1, setext: false},
    %MDEx.Paragraph{nodes: [%MDEx.Code{num_backticks: 1, literal: "ex"}]},
    %MDEx.Paragraph{nodes: [%MDEx.Code{num_backticks: 1, literal: "rs"}]}
  ]
}

Or fragments of a document:

iex> fragment = MDEx.parse_fragment!("Lang: `elixir`")
iex> MDEx.traverse_and_update(fragment, fn
...>   %MDEx.Code{literal: "elixir"} = node -> %{node | literal: "ex"}
...>   node -> node
...> end)
%MDEx.Paragraph{nodes: [%MDEx.Text{literal: "Lang: "}, %MDEx.Code{num_backticks: 1, literal: "ex"}]}

@spec traverse_and_update(MDEx.Document.t(), any(), (MDEx.Document.md_node() ->
                                                 MDEx.Document.md_node())) ::
  MDEx.Document.t()

Low-level function to traverse and update the Markdown document preserving the tree structure format and keeping an accumulator.

See MDEx.Document for more information about the tree structure and for higher-level functions using the Access and Enumerable protocols.

Example

iex> import MDEx.Sigil
iex> doc = ~MD"""
...> # Languages
...>
...> `elixir`
...>
...> `rust`
...> """
iex> MDEx.traverse_and_update(doc, 0, fn
...>   %MDEx.Code{literal: "elixir"} = node, acc -> {%{node | literal: "ex"}, acc + 1}
...>   %MDEx.Code{literal: "rust"} = node, acc -> {%{node | literal: "rs"}, acc + 1}
...>   node, acc -> {node, acc}
...> end)
{%MDEx.Document{
  nodes: [
    %MDEx.Heading{nodes: [%MDEx.Text{literal: "Languages"}], level: 1, setext: false},
    %MDEx.Paragraph{nodes: [%MDEx.Code{num_backticks: 1, literal: "ex"}]},
    %MDEx.Paragraph{nodes: [%MDEx.Code{num_backticks: 1, literal: "rs"}]}
  ]
}, 2}

Also works with fragments.