pyasciidoc

A CJK-friendly AsciiDoc parser for Python, built on markdown-it-py.

Why

Existing Python AsciiDoc implementations (asciidoc, asciidoc3) are ports of the original ASCII-oriented AsciiDoc.py. A quick smoke test shows they fail to recognize emphasis next to Japanese/Chinese/Korean text — *太字*と_斜体_のテスト文です renders as literal, unconverted asterisks/underscores. This is the same class of problem mdit-py-cjk-friendly solves for CommonMark.

Rather than patch a large, legacy, ASCII-oriented codebase for CJK boundary rules, pyasciidoc builds AsciiDoc's syntax as markdown-it-py rules, reusing its CJK-aware delimiter scanning directly.

Scope

v0 is intentionally small and grows by golden-fixture-driven increments (the same discipline used in mdit-py-cjk-friendly and pywashi):

• Document/section headings: = Title .. ====== h6
• Constrained emphasis: *strong*, _em_
• Comments: // line comment, //// block comment (dropped entirely)
• Admonitions: NOTE:/TIP:/IMPORTANT:/WARNING:/CAUTION: paragraphs, or delimited blocks ([NOTE] + ==== ... ====) for multi-paragraph content — real-world documents need annotations, not just prose (added after pyasciidoc started being used for actual organizational docs in aiseed-migration-kit)
• Single-level lists: * item/- item (unordered), . item (ordered, AsciiDoc's bare-dot form)
• Links: https://x[text] (bracketed), bare https://x (auto-detected, trailing punctuation trimmed), link:target[text] (any target)
• Images: block image::target[alt], inline image:target[alt]
• Tables: |=== ... |===, first row is the header
• Quote blocks: [quote, author, source] + ____ ... ____ (attribution optional), or bare ____ ... ____
• Footnotes: footnote:[text] — collected into a list at the end of the document
• Roles: block [.name] applied to the following paragraph (<div class="name">), inline [.name]#text# (<span class="name">). name is not interpreted — it becomes the CSS class verbatim, so meaning lives in the document's own stylesheet, not in pyasciidoc
• Listing/literal blocks: ---- ... ----, rendered verbatim (<pre><code>...</code></pre>) with no inline parsing — for code examples containing */_/: that would otherwise be misread as emphasis or a URL/footnote/link macro

CommonMark's own [text](url), ![alt](src), and <autolink> are disabled — they aren't AsciiDoc syntax, and their label-scanning machinery (parseLinkLabel/skipToken) was the entry point for a hang in 0.4.0 when a document contained a keyword like https/link/image/ footnote immediately before [ (see CHANGELOG 0.4.1). Backticks (`code`, which happens to match AsciiDoc's own constrained-monospace syntax) and HTML entities (&) are kept as an intentional hybrid.

Added in response to real migration needs — see docs/request-website-articles.md for the request and its rationale (measured demand from a 385-article corpus).

Not yet implemented: unconstrained emphasis (**mid-word**), nested lists, cell-spanning tables, include, cross-references, indexes, and inline parsing inside emphasis (e.g. *a link[https://x] inside bold* renders the macro literally — _make_emphasis_rule pushes its content as raw text).

Usage

from pyasciidoc import render

render("= 表題\n\nこれは*重要*です。\n")
# '<h1>表題</h1>\n<p>これは<strong>重要</strong>です。</p>\n'

render("NOTE: これは*重要な*注記です。\n")
# '<div class="admonition note">\n<p class="admonition-label">NOTE</p>\n
#  <p>これは<strong>重要な</strong>注記です。</p>\n</div>\n'

License

MIT