MDEx.Sigil (MDEx v0.7.4)
View SourceSigils for parsing and formatting Markdown between different formats.
Modifiers
HTML
- converts Markdown orMDEx.Document
to HTML
Use EEx.SmartEngine to the document into HTML. It does support assigns
but only the old <%= ... %>
syntax,
and it doesn't support components. It's useful if you want to generate static HTML from Markdown or don't need components or don't want to define an assigns
variable (it's optional).
JSON
- converts Markdown orMDEx.Document
to JSONXML
- converts Markdown orMDEx.Document
to XMLMD
- convertsMDEx.Document
to MarkdownNo modifier (default) - parses a Markdown string into a
MDEx.Document
struct
Note that you should import MDEx.Sigil
to use the ~MD
sigil.
HTML/EEx Format Order
In order to generate the final result, the Markdown string or MDEx.Document
(initial input) is first converted into a static HTML without escaping
the content, then the HTML is passed to the appropriate engine to generate the final output.
Assigns and Expressions
Only the HTML
modifier support assigns, any other modifier will render the assign unmodified.
That's particularly important when generating a MDEx.Document
which does represent the Markdown AST because it must respect
the Markdown content and also be able to convert back to a Markdown string.
Expressions inside code blocks are preserved
Expressions as <%= ... %>
or { ... }
inside code blocks are escaped and not evaluated, ie: they are preserved as is:
assigns = %{title: "Hello"}
~MD"""
`{@title}`
"""HTML
"<p><code>{@title}</code></p>"
Options
All modifiers use these options by default:
[
extension: [
strikethrough: true,
table: true,
autolink: false,
tasklist: true,
superscript: true,
footnotes: true,
description_lists: true,
multiline_block_quotes: true,
alerts: true,
math_dollars: true,
math_code: true,
shortcodes: true,
underline: true,
spoiler: true
],
parse: [relaxed_tasklist_matching: true, relaxed_autolinks: true],
render: [unsafe: true, escape: false]
]
If you need a different set of options, you can call the regular functions in MDEx
to pass the options you need.
Summary
Functions
The ~MD
sigil converts a Markdown string or a %MDEx.Document{}
struct to either one of these formats: MDEx.Document
, Markdown (CommonMark), HTML, JSON or XML.
Functions
The ~MD
sigil converts a Markdown string or a %MDEx.Document{}
struct to either one of these formats: MDEx.Document
, Markdown (CommonMark), HTML, JSON or XML.
Assigns
You can define a variable assigns
in the context of the sigil to evaluate expressions:
iex> assigns = %{lang: ":elixir"}
iex> ~MD|`lang = <%= @lang %>`|HTML
"<p><code>lang = :elixir</code></p>"
Note that only the HTML
modifier support assigns.
Examples
Markdown to MDEx.Document
iex> ~MD[`lang = :elixir`]
%MDEx.Document{nodes: [%MDEx.Paragraph{nodes: [%MDEx.Code{num_backticks: 1, literal: "lang = :elixir"}]}]}
Markdown to HTML
iex> ~MD[`lang = :elixir`]HTML
"<p><code>lang = :elixir</code></p>\n"
Markdown to JSON
iex> ~MD[`lang = :elixir`]JSON
"{"nodes":[{"nodes":[{"literal":"lang = :elixir","num_backticks":1,"node_type":"MDEx.Code"}],"node_type":"MDEx.Paragraph"}],"node_type":"MDEx.Document"}"
Markdown to XML
iex> ~MD[`lang = :elixir`]XML
"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document SYSTEM "CommonMark.dtd">
<document xmlns="http://commonmark.org/xml/1.0">
<paragraph>
<code xml:space="preserve">lang = :elixir</code>
</paragraph>
</document>
"
MDEx.Document
to Markdown
iex> ~MD|%MDEx.Document{nodes: [%MDEx.Paragraph{nodes: [%MDEx.Code{num_backticks: 1, literal: "lang = :elixir"}]}]}|MD
"`lang = :elixir`"
Elixir Expressions
iex> ~MD[## Section <%= 1 + 1 %>]HTML
"<h2>Section 2</h2>"