Packages
ex_doc
0.37.0
0.40.3
0.40.2
0.40.1
0.40.0
0.39.3
0.39.2
0.39.1
0.39.0
0.38.4
0.38.3
0.38.2
0.38.1
0.38.0
0.37.3
0.37.2
0.37.1
0.37.0
0.37.0-rc.2
0.37.0-rc.1
0.37.0-rc.0
0.36.1
0.36.0
0.35.1
0.35.0
0.34.2
0.34.1
0.34.0
0.33.0
0.32.2
0.32.1
0.32.0
0.31.2
0.31.1
0.31.0
0.30.9
0.30.8
0.30.7
0.30.6
0.30.5
0.30.4
0.30.3
0.30.2
0.30.1
0.30.0
0.29.4
0.29.3
0.29.2
0.29.1
0.29.0
0.28.6
0.28.5
0.28.4
0.28.3
0.28.2
0.28.1
0.28.0
0.27.3
0.27.2
0.27.1
0.27.0
0.26.0
0.25.5
0.25.4
0.25.3
0.25.2
0.25.1
0.25.0
0.24.2
0.24.1
0.24.0
0.23.0
0.22.6
0.22.5
0.22.4
0.22.2
0.22.1
0.22.0
0.21.3
0.21.2
0.21.1
0.21.0
0.20.2
0.20.1
0.20.0
0.19.3
0.19.2
0.19.1
0.19.0
0.19.0-rc
0.18.4
0.18.3
0.18.2
0.18.1
0.18.0
retired
0.17.1
0.17.0
retired
0.16.4
0.16.3
0.16.2
0.16.1
0.16.0
0.15.1
0.15.0
0.14.5
0.14.4
0.14.3
0.14.2
0.14.1
0.14.0
0.13.2
0.13.1
0.13.0
0.12.0
0.11.5
0.11.4
0.11.3
0.11.2
0.11.1
0.11.0
0.10.0
0.9.0
0.8.4
0.8.3
0.8.2
0.8.1
0.8.0
0.7.3
0.7.2
0.7.1
0.7.0
0.6.2
0.6.1
0.6.0
0.5.2
0.5.1
ExDoc is a documentation generation tool for Elixir
Current section
Files
Jump to
Current section
Files
lib/ex_doc/markdown/earmark.ex
defmodule ExDoc.Markdown.Earmark do
@moduledoc """
ExDoc extension for the EarmarkParser Markdown parser.
"""
@behaviour ExDoc.Markdown
@admonition_classes ~w(warning error info tip neutral)
@impl true
def available? do
match?({:ok, _}, Application.ensure_all_started(:earmark_parser)) and
Code.ensure_loaded?(EarmarkParser)
end
@doc """
Generate HTML AST.
## Options
* `:gfm` - (boolean) turns on Github Flavored Markdown extensions. Defaults to `true`.
* `: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).
"""
@impl true
def to_ast(text, opts) do
options = [
gfm: true,
line: 1,
file: "nofile",
breaks: false,
pure_links: true,
math: true
]
options = Keyword.merge(options, opts)
case EarmarkParser.as_ast(text, options) do
{:ok, ast, messages} ->
print_messages(messages, options)
fixup(ast)
{:error, ast, messages} ->
print_messages(messages, options)
fixup(ast)
end
end
defp print_messages(messages, options) do
for {_severity, line, message} <- messages do
ExDoc.Utils.warn(message, file: options[:file], line: line)
end
end
defp fixup(list) when is_list(list) do
fixup_list(list, [])
end
defp fixup(binary) when is_binary(binary) do
binary
end
defp fixup({tag, attrs, ast}) do
fixup({tag, attrs, ast, %{}})
end
# Rewrite math back to the original syntax, it's up to the user to render it
defp fixup({"code", [{"class", "math-inline"}], [content], _}) do
"$#{content}$"
end
defp fixup({"code", [{"class", "math-display"}], [content], _}) do
"$$\n#{content}\n$$"
end
# Convert admonition blockquotes to sections for screen reader accessibility
defp fixup(
{"blockquote", blockquote_attrs, [{tag, h_attrs, h_content, h_meta} | rest] = ast,
blockquote_meta}
)
when tag in ["h3", "h4"] do
h_admonition =
with {{"class", classes}, attrs} <- List.keytake(h_attrs, "class", 0),
class_list <- String.split(classes, " "),
adm_classes = [_ | _] <- Enum.filter(class_list, &(&1 in @admonition_classes)) do
{"admonition " <> Enum.join(adm_classes, " "),
[{"class", "admonition-title #{classes}"} | attrs]}
else
_ -> nil
end
section_attrs_fn = fn admonition_classes ->
{classes, attrs} =
case List.keytake(blockquote_attrs, "class", 0) do
nil ->
{admonition_classes, blockquote_attrs}
{{"class", classes}, attrs} ->
{"#{admonition_classes} #{classes}", attrs}
end
[{"role", "note"}, {"class", classes} | attrs]
end
if h_admonition do
{admonition_classes, h_attrs} = h_admonition
section_attrs = section_attrs_fn.(admonition_classes)
h_elem = {tag, h_attrs, h_content, h_meta}
fixup({"section", section_attrs, [h_elem | rest], blockquote_meta})
else
# regular blockquote, copied fixup/1 here to avoid infinite loop
{:blockquote, Enum.map(blockquote_attrs, &fixup_attr/1), fixup(ast), blockquote_meta}
end
end
defp fixup({tag, attrs, ast, meta}) when is_binary(tag) and is_list(attrs) and is_map(meta) do
{fixup_tag(tag), Enum.map(attrs, &fixup_attr/1), fixup(ast), meta}
end
defp fixup({:comment, _, _, _} = comment) do
comment
end
# We are matching on Livebook outputs here, because we prune comments at this point
defp fixup_list(
[
{:comment, _, [~s/ livebook:{"output":true} /], %{comment: true}},
{"pre", pre_attrs, [{"code", code_attrs, [source], code_meta}], pre_meta}
| ast
],
acc
) do
code_attrs =
case Enum.split_with(code_attrs, &match?({"class", _}, &1)) do
{[], attrs} -> [{"class", "output"} | attrs]
{[{"class", class}], attrs} -> [{"class", "#{class} output"} | attrs]
end
code_node = {"code", code_attrs, [source], code_meta}
fixup_list([{"pre", pre_attrs, [code_node], pre_meta} | ast], acc)
end
defp fixup_list([head | tail], acc) do
fixed = fixup(head)
if fixed == [] do
fixup_list(tail, acc)
else
fixup_list(tail, [fixed | acc])
end
end
defp fixup_list([], acc) do
Enum.reverse(acc)
end
defp fixup_tag(tag) do
String.to_atom(tag)
end
defp fixup_attr({name, value}) do
{String.to_atom(name), value}
end
end