Carvex (Carvex v0.0.1)

Copy Markdown View Source

Carve parsing and rendering, backed by the Rust carve-rs engine.

The API follows MDEx:

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

Types

Carve source or a document.

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.

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.

Writes canonical Carve source: carve-rs's formatter for source, and on a document the (possibly edited) tree written back to Carve.

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).

Renders source or a document to Markdown.

Renders source or a document to plain text.

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

source()

@type source() :: String.t() | Carvex.Document.t()

Carve source or a document.

Functions

extensions()

@spec extensions() :: [atom()]

The carve-rs extension names accepted by the :extensions option.

iex> :table_of_contents in Carvex.extensions()
true

lint(source, opts \\ [])

@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

  • :extensions (list of term/0) - As in new/1. The default value is [].

  • :parse (keyword/0) - As in new/1. The default value is [].

  • :caption_hints (boolean/0) - Also flag paragraphs that look like a caption missing its ^ marker. The default value is false.

new(opts \\ [])

@spec new(keyword()) :: Carvex.Document.t()

Builds a document from options. :source is parsed when the pipeline runs.

Options

  • :extensions (list of term/0) - carve-rs built-in extensions, in render order: a name or {name, options}, e.g. [:table_of_contents, heading_permalinks: [symbol: "§"]]. Names are Carvex.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].

    • :positions (boolean/0) - Record pos (codepoint spans) on every node. The default value is false.

    • :lowercase_heading_ids (boolean/0) - Lowercase generated heading ids. The default value is false.

    • :ascii_heading_ids - Transliterate generated heading ids to ASCII. The default value is :off.

  • :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 is true.

    • :source_lines (boolean/0) - Add data-source-line to top-level blocks. The default value is false.

    • :mode - HTML render mode; :static flattens interactive constructs. The default value is :interactive.

    • :safe (boolean/0) - Escape raw HTML (`x`{=html}, ```=html) instead of emitting it. Carvex.Raw nodes are unaffected. The default value is false.

    • :profile - carve-rs feature-restriction profile for untrusted input. The default value is nil.

    • :profile_base_host - Host the profile's link policy treats as internal. The default value is nil.

    • :mention_url - URL template for @user mentions, e.g. "https://example.com/{}". The default value is nil.

    • :tag_url - URL template for #tags. The default value is nil.

    • :symbols (map of String.t/0 keys and String.t/0 values) - :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/2 only: align table columns. The default value is false.

  • :syntax_highlight - Code block highlighting, e.g. [engine: :syntect] or [engine: :lumis]. nil disables it. The default value is nil.

  • :sanitize - ammonia sanitization of the rendered HTML. nil disables it. The default value is nil.

  • :plugins (list of term/0) - Plugins to attach. The default value is [].

  • :assigns - Assigns for Carvex.to_heex/2. The default value is %{}.

parse_document(source, opts \\ [])

@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"}]}]}]

parse_document!(source, opts \\ [])

@spec parse_document!(String.t(), keyword()) :: Carvex.Document.t()

Like parse_document/2 but raises on error.

safe_html(html, opts \\ [])

@spec safe_html(String.t(), keyword()) :: String.t()

Sanitizes and/or escapes an HTML string. Plugins use this to build safe Carvex.Raw nodes.

Options

  • :sanitize - ammonia options merged over Carvex.Document.default_sanitize_options/0, or nil to skip sanitizing. Defaults to the default sanitize options.
  • :escape - HTML-escape & < > " ' after sanitizing. Defaults to false.
  • :heex - replace { and } with &lbrace; / &rbrace; last, so the HTML is not read as HEEx expressions by to_heex/2. Pass Carvex.Document.get_private(doc, :heex, false) from a step. Defaults to false.

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)
"&lt;a&gt;&amp;&lt;/a&gt;"

iex> Carvex.safe_html("<pre>A{b}</pre>", sanitize: nil, heex: true)
"<pre>A&lbrace;b&rbrace;</pre>"

stream(enumerable, opts \\ [])

@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>"}]

to_ansi(source_or_doc, opts \\ [])

@spec to_ansi(source(), keyword()) :: {:ok, String.t()} | {:error, Exception.t()}

Renders source or a document to ANSI-styled terminal text.

to_ansi!(source_or_doc, opts \\ [])

@spec to_ansi!(source(), keyword()) :: String.t()

Like to_ansi/2 but raises on error.

to_carve(source_or_doc, opts \\ [])

@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"}

to_carve!(source_or_doc, opts \\ [])

@spec to_carve!(source(), keyword()) :: String.t()

Like to_carve/2 but raises on error.

to_heex(source, opts \\ [])

(macro)

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 &lbrace;/&rbrace;, 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.

to_heex!(source, opts \\ [])

(macro)

Like to_heex/2 but raises on error.

to_html(source_or_doc, opts \\ [])

@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>"}

to_html!(source_or_doc, opts \\ [])

@spec to_html!(source(), keyword()) :: String.t()

Like to_html/2 but raises on error.

to_markdown(source_or_doc, opts \\ [])

@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"}

to_markdown!(source_or_doc, opts \\ [])

@spec to_markdown!(source(), keyword()) :: String.t()

Like to_markdown/2 but raises on error.

to_plain_text(source_or_doc, opts \\ [])

@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"}

to_plain_text!(source_or_doc, opts \\ [])

@spec to_plain_text!(source(), keyword()) :: String.t()

Like to_plain_text/2 but raises on error.

traverse_and_update(doc, fun)

Traverses and updates the tree post-order; returning nil or :pop removes a node.

traverse_and_update(doc, acc, fun)

Like traverse_and_update/2 with an accumulator; the function returns {node, acc}.