markupz for Erlang

markupz converts HTML fragments to Markdown. It uses z_html_parse from zotonic_stdlib and emits Markdown compatible with markdownz.

The converter has three presets:

• default converts normal content like the faithful preset, but selects only the body from a full HTML document, omits aria-hidden="true" elements, and flattens role="presentation" tables. This is the default.
• faithful converts HTML with direct Markdown equivalents and keeps other elements, document metadata, and presentation markup as raw HTML.
• email produces a readable text/plain alternative for an HTML email. It removes presentation HTML, hidden content, and images, flattens tables, and puts link destinations after their labels.

Usage

1> markupz:to_markdown(<<"<h1>Hello</h1><p>Welcome <b>back</b>.</p>">>).
<<"Hello\n=====\n\nWelcome **back**.">>

2> markupz:to_email_text(EmailHtml).
<<"Hello\n\nRead the update <https://example.test/update>.">>

to_markdown/2 accepts a preset atom or an option map:

markupz:to_markdown(Html, default).
markupz:to_markdown(Html, faithful).
markupz:to_markdown(Html, email).
markupz:to_markdown(Html, #{
    mode => default,
    html => strip,
    tables => text,
    links => inline
}).

The options are:

An option map is merged over the defaults of its mode. For callers that do not want exceptions, convert/1,2 returns {ok, Markdown} or {error, Reason}. to_markdown/1,2 raises error({invalid_html, Reason}) on invalid input or options.

Conversion behavior

The default and faithful presets convert headings, paragraphs, hard breaks, emphasis, strong text, strikethrough, subscript, superscript, links, images, inline and fenced code, block quotes, nested ordered and unordered lists, task-list checkboxes, thematic breaks, and regular tables.

HTML that cannot be represented without losing structure or attributes is serialized as raw HTML when html => keep. For example, a div with classes and a table with rowspan or colspan remain HTML. With html => strip, the wrapper is removed and its readable content is retained.

Semantic asides and Zotonic/reStructuredText-style note admonitions are emitted as Pandoc-style fenced divs:

::: {.aside}
Tangential information.
:::

::: {.note title="Remember"}
Important information.
:::

In faithful mode, other div elements with a class or id and safe attributes are also emitted as fenced divs. Default mode retains generic divs as raw HTML for backward compatibility. Safe fenced-div attributes are id, class, title, role, aria-*, and data-*.

When using the default preset:

• a full document containing a body element contributes only that body's children; fragments without a body are converted in full;
• elements with aria-hidden="true" and their children are omitted;
• tables with role="presentation" are flattened into readable text while normal data tables remain Markdown tables.

The email preset additionally:

• omits head, script, style, template, SVG, and related non-content;
• omits elements with hidden, aria-hidden="true", display:none, visibility:hidden, or mso-hide:all;
• turns nested layout tables into text flow and simple multi-column rows into cell | cell lines;
• writes links as label <destination> and omits images entirely;
• renders headings without Markdown decoration.

The converter parses but does not sanitize input. Raw HTML output is deliberate when html => keep; sanitize untrusted HTML before displaying the generated Markdown with raw HTML enabled.

Build

make compile
make test
make xref
make dialyzer

For the Zotonic email path, the old call:

z_markdown:to_markdown(Html, [no_html, no_tables])

can be replaced with:

markupz:to_email_text(Html)