Carve parsing and rendering, backed by the Rust carve-rs engine.
The API follows MDEx:
to_html/2renders source or aCarvex.Document;to_markdown/2,to_plain_text/2,to_ansi/2andto_carve/2render other outputsparse_document/2returns aCarvex.Documenttree you can query and edit- plugins and pipeline steps (
Carvex.Document) - carve-rs extensions, profiles and safe mode (
new/1options) - syntax highlighting with syntect or Lumis, with code block decorators
- HTML sanitization (ammonia)
- HEEx components and expressions (
to_heex/2,~CRV"..."HEEX) - streaming of chunked input (
stream/2) - linting (
lint/2)
Examples
iex> Carvex.to_html("Hello *world*!")
{:ok, "<p>Hello <strong>world</strong>!</p>"}
iex> Carvex.to_html!("# Hi", render: [sections: false])
"<h1 id=\"Hi\">Hi</h1>"Code block decorators
Block attributes on a code block control highlighting and are never rendered:
{theme=github_dark pre_class="a b" highlight_lines="1,3-5" highlight_lines_style="background: #ff0" highlight_lines_class=hl include_highlights=true}
```elixir
IO.puts("hi")
```Without syntax_highlight:, pre_class becomes a class on the code block and
the other decorators are ignored.
use Carvex
use Carvex requires Carvex, imports Carvex.Sigil, and stores its options in
@carvex_options, which ~CRV uses at compile time.
Summary
Functions
The carve-rs extension names accepted by the :extensions option.
Lints Carve source, returning carve-rs's diagnostics in source order.
Builds a document from options. :source is parsed when the pipeline runs.
Parses source into a Carvex.Document and runs the pipeline.
Like parse_document/2 but raises on error.
Sanitizes and/or escapes an HTML string. Plugins use this to build safe
Carvex.Raw nodes.
Streams chunks of Carve source, emitting {id, %Carvex.Document{}} for each
top-level block that is new or changed. A later emission with the same id
replaces the earlier one; an empty document means the block was removed.
Renders source or a document to ANSI-styled terminal text.
Like to_ansi/2 but raises on error.
Writes canonical Carve source: carve-rs's formatter for source, and on a document the (possibly edited) tree written back to Carve.
Like to_carve/2 but raises on error.
Renders Carve with HEEx components and expressions into a Phoenix.LiveView.Rendered.
Like to_heex/2 but raises on error.
Renders source or a document to HTML. opts are merged into the document
options (see new/1).
Like to_html/2 but raises on error.
Renders source or a document to Markdown.
Like to_markdown/2 but raises on error.
Renders source or a document to plain text.
Like to_plain_text/2 but raises on error.
Traverses and updates the tree post-order; returning nil or :pop removes a node.
Like traverse_and_update/2 with an accumulator; the function returns {node, acc}.
Types
@type source() :: String.t() | Carvex.Document.t()
Carve source or a document.
Functions
@spec extensions() :: [atom()]
The carve-rs extension names accepted by the :extensions option.
iex> :table_of_contents in Carvex.extensions()
true
@spec lint(String.t(), keyword()) :: [Carvex.LintWarning.t()]
Lints Carve source, returning carve-rs's diagnostics in source order.
Offsets in each Carvex.LintWarning are UTF-8 byte offsets into source.
iex> [warning] = Carvex.lint("{#orphan}\n")
iex> warning.rule
"unattached-block-attribute"Options
@spec new(keyword()) :: Carvex.Document.t()
Builds a document from options. :source is parsed when the pipeline runs.
Options
:extensions(list ofterm/0) - carve-rs built-in extensions, in render order: a name or{name, options}, e.g.[:table_of_contents, heading_permalinks: [symbol: "§"]]. Names areCarvex.extensions/0. Options (omitted keys keep the engine default):autolink(allowed_schemes),code_group(wrapper_class,panel_class,label_class,radio_class,id_prefix),external_links(target,rel,nofollow),heading_level_shift(shift),heading_permalinks(symbol,css_class,aria_label,levels,prepend,show_on_hover,copy_to_clipboard,lowercase_ids),heading_reference(css_class),math_block(language),wikilinks(css_class,new_window),heading_numbers(min_level,label,crossref::number | :number_title | :title),table_of_contents(min_level,max_level,list_type::ul | :ol,css_class,position::top | :bottom,lowercase_ids),tabs(mode::css | :aria,wrapper_class,tab_class,label_class,radio_class,id_prefix),fenced_render(languages,css_class,tag,content_mode::text | :json,wrap_in_figure,figure_class),img_fence(allow_style,allow_links,allow_animation,allow_external_images). Putting the option again merges by name: a repeated name replaces its entry in place. The default value is[].:parse(keyword/0) - carve-rs parser options. The default value is[ascii_heading_ids: :off, lowercase_heading_ids: false, positions: false].:render(keyword/0) - carve-rs renderer options. The default value is[align_tables: false, smart_typography: :glyph, symbols: %{}, tag_url: nil, mention_url: nil, profile_base_host: nil, profile: nil, safe: false, mode: :interactive, source_lines: false, sections: true].:sections(boolean/0) - Wrap top-level headings and their content in<section>. The default value istrue.:source_lines(boolean/0) - Adddata-source-lineto top-level blocks. The default value isfalse.:mode- HTML render mode;:staticflattens interactive constructs. The default value is:interactive.:safe(boolean/0) - Escape raw HTML (`x`{=html},```=html) instead of emitting it.Carvex.Rawnodes are unaffected. The default value isfalse.:profile- carve-rs feature-restriction profile for untrusted input. The default value isnil.:profile_base_host- Host the profile's link policy treats as internal. The default value isnil.:mention_url- URL template for@usermentions, e.g."https://example.com/{}". The default value isnil.:tag_url- URL template for#tags. The default value isnil.:symbols(map ofString.t/0keys andString.t/0values) -:name:replacements, emitted as TRUSTED raw HTML. Never build from user input. The default value is%{}.:smart_typography- Markdown output only: emit glyphs or the author's source runs. The default value is:glyph.:align_tables(boolean/0) -to_carve/2only: align table columns. The default value isfalse.
:syntax_highlight- Code block highlighting, e.g.[engine: :syntect]or[engine: :lumis].nildisables it. The default value isnil.:sanitize- ammonia sanitization of the rendered HTML.nildisables it. The default value isnil.:plugins(list ofterm/0) - Plugins to attach. The default value is[].:assigns- Assigns forCarvex.to_heex/2. The default value is%{}.
@spec parse_document(String.t(), keyword()) :: {:ok, Carvex.Document.t()} | {:error, Exception.t()}
Parses source into a Carvex.Document and runs the pipeline.
iex> {:ok, doc} = Carvex.parse_document("Hello *world*")
iex> doc.nodes
[%Carvex.Paragraph{nodes: [%Carvex.Text{value: "Hello "}, %Carvex.Strong{nodes: [%Carvex.Text{value: "world"}]}]}]
@spec parse_document!(String.t(), keyword()) :: Carvex.Document.t()
Like parse_document/2 but raises on error.
Sanitizes and/or escapes an HTML string. Plugins use this to build safe
Carvex.Raw nodes.
Options
:sanitize- ammonia options merged overCarvex.Document.default_sanitize_options/0, ornilto skip sanitizing. Defaults to the default sanitize options.:escape- HTML-escape& < > " 'after sanitizing. Defaults tofalse.:heex- replace{and}with{/}last, so the HTML is not read as HEEx expressions byto_heex/2. PassCarvex.Document.get_private(doc, :heex, false)from a step. Defaults tofalse.
Examples
iex> Carvex.safe_html("<script>x</script><b onclick=\"y\">hi</b>")
"<b>hi</b>"
iex> Carvex.safe_html("<a>&</a>", sanitize: nil, escape: true)
"<a>&</a>"
iex> Carvex.safe_html("<pre>A{b}</pre>", sanitize: nil, heex: true)
"<pre>A{b}</pre>"
@spec stream(Enumerable.t(), keyword()) :: Enumerable.t()
Streams chunks of Carve source, emitting {id, %Carvex.Document{}} for each
top-level block that is new or changed. A later emission with the same id
replaces the earlier one; an empty document means the block was removed.
Each block renders standalone: a footnote reference resolves only if its
definition is in the same block. opts are as in new/1 (plugins attach
once); :source is not accepted.
iex> ["# Hel", "lo\n\nPara"]
...> |> Carvex.stream()
...> |> Enum.map(fn {id, doc} -> {id, Carvex.to_html!(doc, render: [sections: false])} end)
[{0, "<h1 id=\"Hel\">Hel</h1>"}, {0, "<h1 id=\"Hello\">Hello</h1>"}, {1, "<p>Para</p>"}]
@spec to_ansi(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
Renders source or a document to ANSI-styled terminal text.
Like to_ansi/2 but raises on error.
@spec to_carve(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
Writes canonical Carve source: carve-rs's formatter for source, and on a document the (possibly edited) tree written back to Carve.
iex> Carvex.to_carve("# Title")
{:ok, "# Title\n"}
Like to_carve/2 but raises on error.
Renders Carve with HEEx components and expressions into a Phoenix.LiveView.Rendered.
Requires {:phoenix_live_view, "~> 1.2"}. HEEx tags (<.link>, <Mod.fun>,
<:slot>), {@expr} expressions and <%= %> blocks are recognized outside
code; Carve brace syntax like {.class}, [Tab]{kbd}, {^sup^} or a block
attribute line ({loose}) is left alone, so write {@name} rather than a bare
{name} alone on a line. Explicit `...`{=heex} and ```=heex raw
blocks also work.
Braces in the rendered HTML (text, code, attributes, raw html) become
{/}, except inside <script> and <style>.
Assigns come from the :assigns option. The template is compiled at runtime
with the caller's environment, so imports (e.g. Phoenix.Component) apply.
sanitize: is not supported.
Like to_heex/2 but raises on error.
@spec to_html(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
Renders source or a document to HTML. opts are merged into the document
options (see new/1).
iex> Carvex.to_html("/hi/")
{:ok, "<p><em>hi</em></p>"}
Like to_html/2 but raises on error.
@spec to_markdown(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
Renders source or a document to Markdown.
iex> Carvex.to_markdown("/hi/ *there*")
{:ok, "*hi* **there**\n"}
Like to_markdown/2 but raises on error.
@spec to_plain_text(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}
Renders source or a document to plain text.
iex> Carvex.to_plain_text("/hi/ *there*")
{:ok, "hi there\n"}
Like to_plain_text/2 but raises on error.
Traverses and updates the tree post-order; returning nil or :pop removes a node.
Like traverse_and_update/2 with an accumulator; the function returns {node, acc}.