A Carve markup parser and renderer for Elixir.
Parsing and rendering are powered by the carve-rs
engine (crate carve-lang) through a Rustler NIF. The API is a port of
Djot, itself heavily "inspired" by MDEx:
a document AST, a plugin pipeline, syntax highlighting, sanitization, HEEx, and streaming.
Usage
Carvex.to_html("hello *world*!")
# => {:ok, "<p>hello <strong>world</strong>!</p>"}
Carvex.to_html!("# Hi", render: [sections: false])
# => "<h1 id=\"Hi\">Hi</h1>"Carve options
Options are grouped like MDEx's; see Carvex.new/1 for the full list.
parse:-positions(recordposon every node),lowercase_heading_ids,ascii_heading_ids(:off,:fold,:strict).render:-sections(wrap headings in<section>, defaulttrue),source_lines,mode(:interactiveor:static, which flattens interactive constructs),safe,profile,profile_base_host,mention_url,tag_url,symbols,smart_typography(Markdown output),align_tables(to_carve/2).
safe: true escapes raw HTML (`x`{=html}, ```=html) instead of
emitting it. profile: applies one of carve-rs's feature-restriction profiles
(:full, :article, :comment, :minimal) for untrusted input; over-length input
is an error:
Carvex.to_html("`<b>x</b>`{=html}", render: [safe: true])
# => {:ok, "<p><b>x</b></p>"}
Carvex.to_html("# Head\n\ntext", render: [profile: :comment])
# => {:ok, "<p># Head</p>\n<p>text</p>"}
Carvex.to_html(String.duplicate("a", 10_001), render: [profile: :minimal])
# => {:error, %Carvex.CarveError{reason: {:profile_violation, "..."}}}symbols: values are emitted as trusted raw HTML; never build them from user input.
Extensions
carve-rs's built-in extensions are enabled by name, in render order, with options where the extension takes them:
Carvex.to_html!("# Intro\n\n## Usage\n",
extensions: [:table_of_contents, heading_permalinks: [symbol: "§"]],
render: [sections: false]
)
# => "<nav class=\"toc\" aria-label=\"Table of contents\">\n<ul>\n<li><a href=\"#Intro\">Intro</a>…"
Carvex.extensions()
# => [:autolink, :citations, :code_callouts, :code_group, …]Options are validated (unknown names and keys raise). Extensions and profiles also apply when rendering an edited document.
Document AST
Carvex.parse_document/2 returns a %Carvex.Document{} whose nodes (Carvex.Heading,
Carvex.Paragraph, Carvex.Strong, …) mirror Carve's
AST exchange format
and support Access and Enumerable, Floki-style. Attributes are
%Carvex.Attributes{}; child lists are named nodes.
doc = Carvex.parse_document!("# Hi\n\nSome *bold* text")
doc[Carvex.Strong]
# => [%Carvex.Strong{nodes: [%Carvex.Text{value: "bold"}]}]
doc
|> Carvex.Document.update_nodes(Carvex.Strong, &%Carvex.Emphasis{nodes: &1.nodes})
|> Carvex.to_html!()
# => "<section id=\"Hi\">\n <h1>Hi</h1>\n <p>Some <em>bold</em> text</p>\n</section>"Plugins and pipeline
Plugins expose attach/2 and use the same functions as MDEx plugins
(register_options/2, put_options/2, append_steps/2, halt/1, …).
See Carvex.Document for more. Use Carvex.Raw nodes with Carvex.safe_html/2
to inject HTML from a plugin; Carvex.Raw is emitted verbatim regardless of safe:
and profiles.
Carvex.to_html!("hi", plugins: [{MyPlugin, my_option: true}])Carvex sets two private keys that steps can read with Carvex.Document.get_private/3:
:heexistruewhile rendering forto_heex/2or~CRV"..."HEEX.Carvex.Rawis written verbatim, so passheex: truetoCarvex.safe_html/2to turn{/}into entities, or HEEx will read them as expressions.:streamis%{id: id}on each per-block document fromCarvex.stream/2. Skip page-level injections (scripts, styles) there and put the id in element ids so they stay unique across blocks.
defmodule DiagramPlugin do
alias Carvex.Document
def attach(doc, _opts) do
Document.append_steps(doc, diagrams: &diagrams/1)
end
defp diagrams(doc) do
heex? = Document.get_private(doc, :heex, false)
prefix =
case Document.get_private(doc, :stream) do
%{id: id} -> "diagram-#{id}"
nil -> "diagram"
end
{doc, _} =
Carvex.traverse_and_update(doc, 1, fn
%Carvex.CodeBlock{lang: "diagram"} = block, n ->
body = Carvex.safe_html(block.content, sanitize: nil, escape: true, heex: heex?)
{%Carvex.Raw{content: ~s(<pre id="#{prefix}-#{n}" class="diagram">#{body}</pre>)}, n + 1}
node, n ->
{node, n}
end)
doc
end
endSyntax highlighting
Carvex supports syntax highlighting via syntect and
Lumis. Configure it with syntax_highlight:. The
:syntect engine is built in; Lumis needs {:lumis, "~> 0.10"} plus a parser package
such as {:lumis_wasm_elixir, "~> 0.26"} in your deps, and you select it with
engine: :lumis.
Carvex.to_html!(source, syntax_highlight: [engine: :syntect, opts: [theme: "Dracula"]])
Carvex.to_html!(source, syntax_highlight: [engine: :lumis, opts: [formatter: {:html_inline, theme: "onedark"}]])Code blocks take decorators as Carve block attributes on the line above the fence:
{theme=Dracula pre_class="a b" highlight_lines="1,3-5" highlight_lines_class=hl}
```elixir
IO.puts("hi")
```| Decorator | Effect |
|---|---|
theme | Overrides the configured theme (syntect, Lumis :html_inline / :terminal) |
pre_class | Extra classes on <pre> |
highlight_lines | Lines to highlight: comma-separated N or N-M; invalid entries are skipped |
highlight_lines_style | Inline style for highlighted lines |
highlight_lines_class | Extra class for highlighted lines |
include_highlights | true adds a data-highlight attribute with the scope name (Lumis :html_inline / :html_multi_themes only) |
Decorators never appear in the output. Without syntax_highlight:, pre_class still
becomes a class on <pre> and the rest are ignored. Code blocks whose language an
enabled extension renders (e.g. mermaid with :fenced_render, math with
:math_block) are left to that extension.
Sanitization
Carvex.to_html!(source, sanitize: Carvex.Document.default_sanitize_options())
Carvex.safe_html("<script>x</script><b>ok</b>")
# => "<b>ok</b>"Sanitizing runs on the final HTML, including Carvex.Raw nodes from plugins. The
defaults keep carve's own footnote, section and task-list markup. Scripts and
attributes outside the allowlist (such as phx-update) are removed unless you allow
them, e.g. with add_tag_attributes: or add_generic_attribute_prefixes:. You can't
combine sanitize: with HEEx rendering; to_heex/2 returns a Carvex.CarveError
with reason :sanitize_unsupported_in_heex.
HEEx
With {:phoenix_live_view, "~> 1.2"}, Carve can contain components and expressions:
use Carvex
import Phoenix.Component
def render(assigns) do
~CRV"""
Hello {@name}
<.link href="/x">go</.link>
"""HEEX
end
Carvex.to_heex!("Hi {@name}", assigns: %{name: "Ann"})Carve's own brace syntax ({.class}, [Tab]{kbd}, {^sup^}, {,sub,}, {:fr},
{~old~>new~}, …) is left alone. A bare {name} alone on a line is a Carve block
attribute line, so write {@name} or put the expression inline. Braces in the
rendered HTML become entities, except inside <script> and <style>.
to_heex/2 and to_heex!/2 are macros, available after use Carvex or
require Carvex. They compile the template at runtime in the caller's environment,
so imports such as Phoenix.Component apply. The compiler can't see that, though,
and warns that an import only the template uses is unused. ~CRV"..."HEEX compiles
the template at compile time and doesn't trigger the warning.
Sigil
use Carvex (or import Carvex.Sigil) provides ~CRV, evaluated at compile time:
~CRV"..." returns a %Carvex.Document{}, ~CRV"..."HTML the HTML string, and
~CRV"..."HEEX compiles a HEEx template whose code needs an assigns variable in
scope where the sigil is used (as in render(assigns) above). Options given to
use Carvex, opts apply to every ~CRV in the module.
use Carvex
~CRV"""
Some text \
compiled to HTML at compile time!
"""HTML
# => "<p>Some text <br>\ncompiled to HTML at compile time!</p>"Other outputs
Carvex.to_markdown!("/hi/ *there* =mark=")
# => "*hi* **there** <mark>mark</mark>\n"
Carvex.to_plain_text!("# Title\n\n/hi/ *there*")
# => "Title\n\nhi there\n"
Carvex.to_ansi!("*bold*")
Carvex.to_carve!("# Title\n\n- a\n- b")
# => "# Title\n\n- a\n- b\n"to_carve/2 is carve-rs's canonical writer (formatter); given a document it writes
the (possibly edited) tree back to Carve source. All outputs accept documents and the
same options as to_html/2.
Linting
Carvex.lint("{#orphan}\n")
# => [%Carvex.LintWarning{line: 1, column: 1, rule: "unattached-block-attribute",
# message: "This block attribute reaches no block: …", start_offset: 0, end_offset: 9}]start_offset/end_offset are UTF-8 byte offsets, so
binary_part(source, w.start_offset, w.end_offset - w.start_offset) is the flagged text.
Streaming
chunks
|> Carvex.stream()
|> Enum.each(fn {id, doc} -> send(self(), {:block, id, Carvex.to_html!(doc)}) end)Each emission replaces the block with the same id. Each block renders standalone,
so a footnote reference resolves only when its definition is in the same block.
Plugins attach once and their steps run on every emitted block document (see the
:stream private key above).
Not exposed
carve-rs features this package does not bind: static-mode build renderers (mermaid
and math callbacks), mention/tag resolver callbacks, {{ include }} expansion, and
the importers (Markdown, HTML, Djot, BBCode to Carve).
Installation
def deps do
[
{:carvex, "~> 0.0.1"}
]
endSee also
This package ports djot to the Carve language, and is inspired by the excellent mdex package.