Metadata-Version: 2.4
Name: pyasciidoc
Version: 0.4.0
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

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.

## 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
