Earmark v1.1.0 Earmark
Dependency
{ :earmark, "> x.y.z" }
Usage
API
{html_doc, error_messages} = Earmark.as_html(markdown)
{html_doc, error_messages} = Earmark.as_html!(markdown, options)
Options can be passed into as_html
according to the documentation.
html_doc = Earmark.as_html!(markdown)
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
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-"})
Supports
Standard Gruber markdown.
Extensions
Tables
Github Flavored Markdown tables are supported
State | Abbrev | Capital
----: | :----: | -------
Texas | TX | Austin
Maine | ME | Augusta
Tables may have leading and trailing vertical bars on each line
| State | Abbrev | Capital |
| ----: | :----: | ------- |
| Texas | TX | Austin |
| Maine | ME | Augusta |
Tables need not have headers, in which case all column alignments default to left.
| Texas | TX | Austin |
| Maine | ME | Augusta |
Currently we assume there are always spaces around interior vertical bars. It isn’t clear what the expectation is.
Adding HTML attributes with the IAL extension
HTML attributes can be added to any block-level element. We use
the Kramdown syntax: add the line {:
attrs }
following the block.
attrs can be one or more of:
.className
#id
- name=value, name=”value”, or name=’value’
Malformed attributes are ignored and a warning is issued to stderr.
If you need to render IAL-like test verbatim escape it:
{:alpha, 42}
This of course is not necessary in code blocks or text lines containing an IAL-like string, as in
the returned tuple should be {:error, "I wish you hadn't done that"}
For example:
# Warning
{: .red}
Do not turn off the engine
if you are at altitude.
{: .boxed #warning spellcheck="true"}
Limitations
Nested block-level HTML is correctly handled only if each HTML tag appears on its own line. So
hellowill work. However. the following won’t
helloJohn Gruber’s tests contain an ambiguity when it comes to lines that might be the start of a list inside paragraphs.
One test says that
This is the text
of a paragraph that I wrote
is a single paragraph. The “*” is not significant. However, another test has
A list item
an another
and expects this to be a nested list. But, in reality, the second could just be the continuation of a paragraph.
I’ve chosen always to use the second interpretation—a line that looks like a list item will always be a list item.
Rendering of block and inline elements.
Block or void HTML elements that are at the absolute beginning of a line end the preceding paragraph.
Thusly
mypara
Becomes
mypara
While
mypara
will be transformed into
mypara
Integration
Syntax Highlightning
All backquoted or fenced code blocks with a language string are rendered with the given language as a class attribute of the code tag.
For example:
```elixir
@tag :hello
```
will be rendered as
<pre><code class="elixir">...
If you want to integrate with a syntax highlighter with different conventions you can add more classes by specifying prefixes that will be put before the language string.
Prism.js for example needs a class language-elixir
. In order to achieve that goal you can add language-
as a code_class_prefix
to Earmark.Options
.
In the following example we want more than one additional class, so we add more prefixes.
Earmark.as_html!(..., %Earmark.Options{code_class_prefix: "lang- language-"})
which is rendering
<pre><code class="elixir lang-elixir language-elixir">...
As for all other options code_class_prefix
can be passed into the earmark
executable as follows:
earmark --code-class-prefix "language- lang-" ...
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 Markdown.html
if you cannot trust the input
and are to serve the produced HTML on the Web.
Author
Copyright © 2014 Dave Thomas, The Pragmatic Programmers @/+pragdave, dave@pragprog.com
Licensed under the same terms as Elixir, which is Apache 2.0.
Summary
Functions
Given a markdown document (as either a list of lines or
a string containing newlines), returns a tuple containing either
{:ok, html_doc}
, or {:error, html_doc, error_messages}
Where html_doc
is an HTML representation of the markdown document and
error_messages
is a list of strings representing information concerning
the errors that occurred during parsing
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 prinetd to stderr
Given a markdown document (as either a list of lines or a string containing newlines), return a parse tree and the context necessary to render the tree
Functions
as_html(String.t | [String.t], %Earmark.Options{breaks: term, code_class_prefix: term, do_sanitize: term, do_smartypants: term, file: term, footnote_offset: term, footnotes: term, gfm: term, line: term, mapper: term, messages: term, pedantic: term, plugins: term, renderer: term, sanitize: term, smartypants: term}) :: {String.t, [String.t]}
Given a markdown document (as either a list of lines or
a string containing newlines), returns a tuple containing either
{:ok, html_doc}
, or {:error, html_doc, error_messages}
Where html_doc
is an HTML representation of the markdown document and
error_messages
is a list of strings representing information concerning
the errors that occurred during parsing.
The options are a %Earmark.Options{}
structure:
renderer
: ModuleNameThe module used to render the final document. Defaults to
Earmark.HtmlRenderer
gfm
: booleanTrue by default. Turns on Github Flavored Markdown extensions
breaks
: booleanOnly applicable if
gfm
is enabled. Makes all line breaks significant (so every line in the input is a new line in the output.smartypants
: booleanTurns on smartypants processing, so quotes become curly, two or three hyphens become en and em dashes, and so on. True by default.
So, to format the document in original
and disable smartypants,
you’d call
alias Earmark.Options
Earmark.as_html(original, %Options{smartypants: false})
as_html!(String.t | [String.t], %Earmark.Options{breaks: term, code_class_prefix: term, do_sanitize: term, do_smartypants: term, file: term, footnote_offset: term, footnotes: term, gfm: term, line: term, mapper: term, messages: term, pedantic: term, plugins: term, renderer: term, sanitize: term, smartypants: term}) :: String.t
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 prinetd to stderr.
Otherwise it behaves exactly as as_html
.
parse(String.t | [String.t], %Earmark.Options{breaks: term, code_class_prefix: term, do_sanitize: term, do_smartypants: term, file: term, footnote_offset: term, footnotes: term, gfm: term, line: term, mapper: term, messages: term, pedantic: term, plugins: term, renderer: term, sanitize: term, smartypants: term}) :: {Earmark.Block.ts, %Earmark.Context{footnotes: term, links: term, options: term, rules: term}}
Given a markdown document (as either a list of lines or a string containing newlines), return a parse tree and the context necessary to render the tree.
The options are a %Earmark.Options{}
structure. See as_html!
for more details.
Accesses current hex version of the Earmark
application. Convenience for
iex
usage.