Earmark

Abstract Syntax Tree and Rendering

The AST generation has now been moved out to EarmarkParser which is installed as a dependency.

This brings some changes to this documentation and also deprecates the usage of Earmark.as_ast

Earmark takes care of rendering the AST to HTML, exposing some AST Transformation Tools and providing a CLI as escript.

Therefore you will not find a detailed description of the supported Markdown here anymore as this is done in here.

Earmark.as_ast

WARNING: This is just a proxy towards Earmark.Parser.as_ast and is deprecated, it will be removed in version 1.5!

Replace your calls to Earmark.as_ast with EarmarkParse.as_ast as soon as possible.

N.B. If all you use is Earmark.as_ast consider only using Earmark.Parser.

Also please refer yourself to the documentation of EarmarkParser.

The function is described below and the other two API functions as_html and as_html! are now based upon the structure of the result of as_ast.

{:ok, ast, []}                   = Earmark.Parser.as_ast(markdown)
{:ok, ast, deprecation_messages} = Earmark.Parser.as_ast(markdown)
{:error, ast, error_messages}    = Earmark.Parser.as_ast(markdown)

Earmark.as_html

{:ok, html_doc, []}                   = Earmark.as_html(markdown)
{:ok, html_doc, deprecation_messages} = Earmark.as_html(markdown)
{:error, html_doc, error_messages}    = Earmark.as_html(markdown)

Earmark.as_html!

html_doc = Earmark.as_html!(markdown, options)

Formats the error_messages returned by as_html and adds the filename to each. Then prints them to stderr and just returns the html_doc

Options

Options can be passed into as as_html/2 or as_html!/2 according to the documentation. A keyword list with legal options (c.f. Earmark.Options) or an Earmark.Options struct are accepted.

{status, html_doc, errors} = Earmark.as_html(markdown, options)
html_doc = Earmark.as_html!(markdown, options)
{status, ast, errors} = Earmark.Parser.as_ast(markdown, options)

Rendering

All options passed through to Earmark.Parser.as_ast are defined therein, however some options concern only the rendering of the returned AST

These are:

• compact_output: defaults to false

Normally Earmark aims to produce Human Readable output.

This will give results like these:

iex(1)> markdown = "# Hello\nWorld"
...(1)> Earmark.as_html!(markdown, compact_output: false)
"<h1>\nHello</h1>\n<p>\nWorld</p>\n"

But sometimes whitespace is not desired:

iex(2)> markdown = "# Hello\nWorld"
...(2)> Earmark.as_html!(markdown, compact_output: true)
"<h1>Hello</h1><p>World</p>"

Be cautions though when using this options, lines will become loooooong.

escape: defaulting to true

If set HTML will be properly escaped

  iex(3)> markdown = "Hello<br>World"
  ...(3)> Earmark.as_html!(markdown)
  "<p>\nHello&lt;br&gt;World</p>\n"

However disabling escape: gives you maximum control of the created document, which in some cases (e.g. inside tables) might even be necessary

  iex(4)> markdown = "Hello<br>World"
  ...(4)> Earmark.as_html!(markdown, escape: false)
  "<p>\nHello<br>World</p>\n"

inner_html: defaulting to false

This is especially useful inside templates, when a block element will disturb the layout as in this case

<span><%= Earmark.as_html!(....)%></span>
<span><%= Earmark.as_html!(....)%></span>

By means of the inner_html option the disturbing paragraph can be removed from as_html!'s output

  iex(5)> markdown = "Hello<br>World"
  ...(5)> Earmark.as_html!(markdown, escape: false, inner_html: true)
  "Hello<br>World\n"

N.B. that this applies only to top level paragraphs, as can be seen here

  iex(6)> markdown = "- Item\n\nPara"
  ...(6)> Earmark.as_html!(markdown, inner_html: true)
  "<ul>\n  <li>\nItem  </li>\n</ul>\nPara\n"

• postprocessor: defaults to nil

Before rendering, the AST is transformed by a postprocessor. For details, see the description of Earmark.Transform.map_ast below which will accept the same postprocessor. As a matter of fact, specifying postprocessor: fun is conceptually the same as

          markdown
          |> Earmark.Parser.as_ast
          |> Earmark.Transform.map_ast(fun)
          |> Earmark.Transform.transform

with all the necessary bookkeeping for options and messages

• renderer: defaults to Earmark.HtmlRenderer

  The module used to render the final document.

smartypants: defaulting to true

If set the following replacements will be made during rendering of inline text

"---" → "—"
"--" → "–"
"' → "’"
?" → "”"
"..." → "…"

Command line

    $ mix escript.build
    $ ./earmark file.md

Some options defined in the Earmark.Options struct can be specified as command line switches.

Use

    $ ./earmark --help

to find out more, but here is a short example

    $ ./earmark --smartypants false --code-class-prefix "a- b-" file.md

will call

    Earmark.as_html!( ..., %Earmark.Options{smartypants: false, code_class_prefix: "a- b-"})

Timeouts

By default, that is if the timeout option is not set Earmark uses parallel mapping as implemented in Earmark.pmap/2, which uses Task.await with its default timeout of 5000ms.

In rare cases that might not be enough.

By indicating a longer timeout option in milliseconds Earmark will use parallel mapping as implemented in Earmark.pmap/3, which will pass timeout to Task.await.

In both cases one can override the mapper function with either the mapper option (used if and only if timeout is nil) or the mapper_with_timeout function (used otherwise).

For the escript only the timeout command line argument can be used.

Security

Please be aware that Markdown is not a secure format. It produces HTML from Markdown and HTML. It is your job to sanitize and or filter the output of Earmark.as_html if you cannot trust the input and are to serve the produced HTML on the Web.