# Earmark—A Pure Elixir Markdown Processor
[](https://travis-ci.org/pragdave/earmark)
[](https://hex.pm/packages/earmark)
<!-- moduledoc: Earmark -->
## Dependency
{ :earmark, "> x.y.z" }
## Usage
### API
html_doc = Earmark.to_html(markdown)
html_doc = Earmark.to_html(markdown, options)
(See the documentation for `to_html` for options)
### 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.to_html( ..., %Earmark.Options{smartypants: false, code_class_prefix: "a- b-"})
## Supports
Standard [Gruber markdown][gruber].
[gruber]: <http://daringfireball.net/projects/markdown/syntax>
## 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
<div>
<div>
hello
</div>
</div>
will work. However. the following won't
<div><div>
hello
</div></div>
* John 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 preceeding paragraph.
Thusly
mypara
<hr>
Becomes
<p>mypara</p>
<hr>
While
mypara
<hr>
will be transformed into
<p>mypara
<hr></p>
## 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.to_html(..., %Earmark.Options{code_class_prefix: "lang- language-"})
which is rendering
<pre><code class="elixir lang-elixiri 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.
<!-- endmoduledoc: Earmark -->
# Details
<!-- doc: Earmark.to_html -->
Given a markdown document (as either a list of lines or
a string containing newlines), return an HTML representation.
The options are a `%Earmark.Options{}` structure:
* `renderer`: ModuleName
The module used to render the final document. Defaults to
`Earmark.HtmlRenderer`
* `gfm`: boolean
True by default. Turns on Github Flavored Markdown extensions
* `breaks`: boolean
Only applicable if `gfm` is enabled. Makes all line breaks
significant (so every line in the input is a new line in the
output.
* `smartypants`: boolean
Turns 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
result = Earmark.to_html(original, %Options{smartypants: false})
<!-- enddoc: Earmark.to_html -->
# LICENSE
Same as Elixir, which is Apache License v2.0. Please refer to [LICENSE](LICENSE) for details.
