Earmark (Earmark v1.4.14) View Source

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 EarmarkParser.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 EarmarkParser.

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, []}                   = EarmarkParser.as_ast(markdown)
{:ok, ast, deprecation_messages} = EarmarkParser.as_ast(markdown)
{:error, ast, error_messages}    = EarmarkParser.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} = EarmarkParser.as_ast(markdown, options)

Rendering

All options passed through to EarmarkParser.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(0)> markdown = "# Hello\nWorld"
...(0)> Earmark.as_html!(markdown, compact_output: false)
"<h1>\nHello</h1>\n<p>\nWorld</p>\n"

But sometimes whitespace is not desired:

iex(1)> markdown = "# Hello\nWorld"
...(1)> 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(2)> markdown = "Hello<br />World"
  ...(2)> 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(3)> markdown = "Hello<br />World"
  ...(3)> Earmark.as_html!(markdown, escape: false)
  "<p>\nHello<br />World</p>\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 conecptionnaly the same as

      markdown
      |> EarmarkParser.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.

Link to this section Summary

Functions

DEPRECATED call EarmarkParser.as_ast instead

A convenience method that always returns an HTML representation of the markdown document passed in. In case of the presence of any error messages they are printed to stderr.

Accesses current hex version of the Earmark application. Convenience for iex usage.

Link to this section Types

Specs

ast() :: [ast_node()]

Specs

ast_attribute() :: {ast_attribute_name(), ast_attribute_value()}

Specs

ast_attribute_name() :: binary()

Specs

ast_attribute_value() :: binary()

Specs

ast_attributes() :: [ast_attribute()]

Specs

ast_meta() :: map()

Specs

ast_node() :: binary() | ast_tuple()

Specs

ast_tag() :: binary()

Specs

ast_tuple() :: {ast_tag(), ast_attributes(), ast(), ast_meta()}

Link to this section Functions

Link to this function

as_ast(lines, options \\ %Options{})

View Source

DEPRECATED call EarmarkParser.as_ast instead

Link to this function

as_html!(lines, options \\ %Options{})

View Source

A convenience method that always returns an HTML representation of the markdown document passed in. In case of the presence of any error messages they are printed to stderr.

Otherwise it behaves exactly as as_html.

Link to this function

postprocessed_ast(lines, options \\ %{})

View Source

Accesses current hex version of the Earmark application. Convenience for iex usage.