Metadata-Version: 2.4
Name: pyasciidoc
Version: 0.4.2
Summary: A CJK-friendly AsciiDoc parser for Python, built on markdown-it-py.
Project-URL: Homepage, https://github.com/aiseed-dev/pyasciidoc
Author: aiseed-dev
License: MIT
License-File: LICENSE
Keywords: asciidoc,chinese,cjk,japanese,korean,markdown-it-py
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.9
Requires-Dist: markdown-it-py<4,>=2.0
Requires-Dist: mdit-py-cjk-friendly>=0.3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Description-Content-Type: text/markdown

# pyasciidoc

A CJK-friendly AsciiDoc parser for Python, built on
[markdown-it-py](https://github.com/executablebooks/markdown-it-py).

## Why

Existing Python AsciiDoc implementations
([asciidoc](https://github.com/asciidoc/asciidoc-py3),
[asciidoc3](https://asciidoc3.org)) 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](https://github.com/aiseed-dev/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](https://github.com/aiseed-dev/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 (`&amp;`) are kept as an intentional hybrid.

Added in response to real migration needs — see
[docs/request-website-articles.md](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

```python
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
