pyxmark 0.1.1

xmark

Modern parser and HTML renderer for XMD — a markdown dialect for complex article layouts.

Plain markdown runs out of room once an article needs pull quotes, sidebars, terminal transcripts, image galleries and typographic polish. XMD adds those as first-class syntax, and xmark renders them to HTML with stable, sequential element ids you can link to. Built on mistune.

Install

pip install pyxmark

Usage

from xmark import render_markdown

html = render_markdown(
    "First paragraph\n\nSecond line",
    target="web",          # or "pdf"
    article_id=42,
    uploads_path="https://cdn.example.com/uploads",
    default_lang="python",
    paywall_marker="",     # substituted for the ------ cut line
    wrapper=None,          # e.g. "xmd" -> wraps output in <article>
)

CLI reads stdin, writes HTML to stdout:

echo "Hello **world**" | xmark --target web --article-id 1

XMD syntax

Standard markdown (headings, lists, blockquotes, fenced code, tables, inline formatting, links, images) via mistune with the strikethrough and table plugins. Bare URLs are not autolinked, and task lists are not special.

Extensions beyond standard markdown:

Rendering details

Element ids. Every rendered element gets a sequential id (id=p1, id=code2, id=h2-3, …), assigned children-first, so a nested list gets lower ids than its parent. Ids are stable for a given input, which makes them usable as deep links.

Code highlighting. Pygments, emitted line-wise as <code class='highlight <lang>'><div class=wrapper><div class="l l1">… with per-line divs and short token classes, so blocks can wrap under white-space: pre.

Typography. The typograf stage processes text nodes only, skipping h1..h4, pre, code, kbd, script, style and math elements plus the nobr and term classes. It injects soft hyphens into Russian words, glues prepositions and numbers with  , and converts -> arrows. The document is normalized on the way out: entities decoded, &/</> re-escaped, attributes double-quoted, and void elements serialized as <br>, <hr>, <img …>.

Uploads. Relative src= paths are prefixed with uploads_path; no files are fetched.

Two behaviors worth knowing when you diff output:

• A catcher block shares one id. Every | line of a block renders with the same id=catcherN; the next block gets N+1.
• Gallery tables are preceded by an empty <p> — <p id=pN></p><table∆ class='figtable…'> — because the table is hoisted out of its paragraph wrapper.

Development

uv sync
uv run pytest
uv run ruff check
uv run ruff format