illusion-markdown

Official Python bindings for illusion Markdown (MDI). illusion-markdown parses complete MDI documents, returns the versioned document IR, and renders HTML, text, EPUB, and DOCX through the canonical Rust implementation. Python is an ergonomic API layer only: it does not carry a second Markdown parser or renderer.

Read the Python API documentation →

Install

pip install illusion-markdown

The PyPI distribution is illusion-markdown; the Python import namespace is mdi. Python 3.10 or newer is required.

Quick start

import mdi

source = """---
title: 東京の夜
lang: ja
---

# {東京|とうきょう}の夜

第^12^話
"""

result = mdi.parse(source)
print(result["document"]["children"][0]["type"])

html = mdi.render_html(source)
open("book.html", "w", encoding="utf-8").write(html)

parse() returns a JSON-compatible dictionary with the MDI syntax version, IR version, parser capabilities, document tree, and recoverable diagnostics. Every source-backed span is a half-open UTF-8 byte range.

API

Function	Result
`mdi.parse(source)`	Versioned document IR and diagnostics.
`mdi.serialize_mdi(source)`	Canonical MDI/Markdown source.
`mdi.render_html(source)`	A standalone HTML document.
`mdi.render_text(source)`	Deterministic plain text.
`mdi.render_text_format(source, format)`	TXT, ruby, Narou, Kakuyomu, Aozora, or note text.
`mdi.render_epub(source)`	EPUB 3 archive bytes.
`mdi.render_docx(source)`	DOCX archive bytes.

epub_bytes = mdi.render_epub("# Chapter\n\nText")
with open("book.epub", "wb") as output:
    output.write(epub_bytes)

See the official Python documentation for API details, the complete MDI syntax, output formats, and architecture.

Platform support

Prebuilt wheels are published for macOS (Intel and Apple Silicon), Linux x64, and Windows x64. A source distribution is also available for other platforms with a supported Rust toolchain.

Development

The binding is tested against a locally built native extension. From this directory, use Python 3.10 or newer:

python -m pip install -e ".[test]"
python -m pytest --cov=mdi --cov-branch

The test suite covers the public Python contract, including the versioned IR, UTF-8 byte spans, diagnostics, all text exports, archive structure, type boundaries, and the stable API surface.

License

MIT

Automatic warichu presentation layout

The Rust core supplies two lines at 50% body size with no line gap. Capacity is measured in half-em units at the note font size; it is a character-width estimate, not exact proportional-font measurement. The first fragment can use the space remaining on the current body line; following fragments use the full capacity.

from mdi import layout_warichu
fragments = layout_warichu([{"type": "text", "value": "一二三四五六"}], 4, first_capacity=2)

Results contain lines, html, widths, overflow, hardBreakAfter, and sources. Each source has a child-index path relative to the input inline array, half-open startUtf8 / endUtf8 offsets into that leaf's visible text, and an indivisible group ID. A cluster crossing formatting boundaries shares a group. Ruby, tcy, no-break and unknown containers remain whole; their coordinates use projected visible text (ruby base, excluding its reading). Oversized groups remain available and report overflow. Author hard breaks are retained; automatic splits never enter canonical MDI or plain text.

The C ABI provides mdi_layout_warichu_json, taking inline-array JSON and options JSON (firstCapacity, continuationCapacity) and returning the same JSON through mdi_ffi_result. Release both returned buffers with mdi_free_buffer. Static HTML/EPUB includes readable precomputed lines; reader reflow can differ. DOCX uses native Word combination groups; XML verification is not a Word rendering test. Custom sizes, line counts and manual splitting remain tracked in MDI #85.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

illusion_markdown-2.0.5.tar.gz (129.7 kB view details)

Uploaded Sep 7, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

illusion_markdown-2.0.5-cp310-abi3-win_amd64.whl (836.1 kB view details)

Uploaded Sep 7, 2026 CPython 3.10+Windows x86-64

illusion_markdown-2.0.5-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.1 MB view details)

Uploaded Sep 7, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

illusion_markdown-2.0.5-cp310-abi3-macosx_11_0_arm64.whl (956.4 kB view details)

Uploaded Sep 7, 2026 CPython 3.10+macOS 11.0+ ARM64

illusion_markdown-2.0.5-cp310-abi3-macosx_10_12_x86_64.whl (974.3 kB view details)

Uploaded Sep 7, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file illusion_markdown-2.0.5.tar.gz.

File metadata

Download URL: illusion_markdown-2.0.5.tar.gz
Upload date: Sep 7, 2026
Size: 129.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for illusion_markdown-2.0.5.tar.gz
Algorithm	Hash digest
SHA256	`582854ce43ea9c9e721ba0836e6b393e91484d0b1d3819a34c6dc91168d8338a`
MD5	`da70982e24fe6007f0c20d475a7a5abd`
BLAKE2b-256	`a2186765d2557fe943f88366df05ed4145fe193cbaaf241287b1f21574106ef5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for illusion_markdown-2.0.5.tar.gz:

Publisher: release-pypi.yml on illusions-lab/MDI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: illusion_markdown-2.0.5.tar.gz
- Subject digest: 582854ce43ea9c9e721ba0836e6b393e91484d0b1d3819a34c6dc91168d8338a
- Sigstore transparency entry: 2746691927
- Sigstore integration time: Sep 7, 2026
Source repository:
- Permalink: illusions-lab/MDI@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Branch / Tag: refs/heads/main
- Owner: https://github.com/illusions-lab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yml@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Trigger Event: workflow_dispatch

File details

Details for the file illusion_markdown-2.0.5-cp310-abi3-win_amd64.whl.

File metadata

Download URL: illusion_markdown-2.0.5-cp310-abi3-win_amd64.whl
Upload date: Sep 7, 2026
Size: 836.1 kB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for illusion_markdown-2.0.5-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`655cb23f3522662f72990fafb5bcec4fdc17bdd0636a13e73750bc03afabae56`
MD5	`bb0d2767e886296f43df92a6dd34ce91`
BLAKE2b-256	`89d2ec666362b57ac62ba66f1d176737774f4fc3487e60767e05863352f4ad99`

See more details on using hashes here.

Provenance

The following attestation bundles were made for illusion_markdown-2.0.5-cp310-abi3-win_amd64.whl:

Publisher: release-pypi.yml on illusions-lab/MDI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: illusion_markdown-2.0.5-cp310-abi3-win_amd64.whl
- Subject digest: 655cb23f3522662f72990fafb5bcec4fdc17bdd0636a13e73750bc03afabae56
- Sigstore transparency entry: 2746691954
- Sigstore integration time: Sep 7, 2026
Source repository:
- Permalink: illusions-lab/MDI@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Branch / Tag: refs/heads/main
- Owner: https://github.com/illusions-lab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yml@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Trigger Event: workflow_dispatch

File details

Details for the file illusion_markdown-2.0.5-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: illusion_markdown-2.0.5-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Sep 7, 2026
Size: 1.1 MB
Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for illusion_markdown-2.0.5-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`b17c7a2aa2448ab80e94a2bea05f90120e0c7cb14bbade435a8b9dd081d82ad3`
MD5	`939973334442c9b684b6cff015d3ec48`
BLAKE2b-256	`e411f09e0ab0cbf1687212bc6dc6f17ba5e7216453c41e943b4c55eed7450407`

See more details on using hashes here.

Provenance

The following attestation bundles were made for illusion_markdown-2.0.5-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-pypi.yml on illusions-lab/MDI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: illusion_markdown-2.0.5-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: b17c7a2aa2448ab80e94a2bea05f90120e0c7cb14bbade435a8b9dd081d82ad3
- Sigstore transparency entry: 2746691988
- Sigstore integration time: Sep 7, 2026
Source repository:
- Permalink: illusions-lab/MDI@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Branch / Tag: refs/heads/main
- Owner: https://github.com/illusions-lab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yml@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Trigger Event: workflow_dispatch

File details

Details for the file illusion_markdown-2.0.5-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: illusion_markdown-2.0.5-cp310-abi3-macosx_11_0_arm64.whl
Upload date: Sep 7, 2026
Size: 956.4 kB
Tags: CPython 3.10+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for illusion_markdown-2.0.5-cp310-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`f500b4d0130624054e3ac57928d402642dab420eff500ff7a3e4ef1a70e56a13`
MD5	`761ad8499bd6067f7e0b3f2b14366b05`
BLAKE2b-256	`b3a634a319d4b7e18061738d9feb0259a8a55421f36ce57a31779ba83bf079e5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for illusion_markdown-2.0.5-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release-pypi.yml on illusions-lab/MDI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: illusion_markdown-2.0.5-cp310-abi3-macosx_11_0_arm64.whl
- Subject digest: f500b4d0130624054e3ac57928d402642dab420eff500ff7a3e4ef1a70e56a13
- Sigstore transparency entry: 2746692024
- Sigstore integration time: Sep 7, 2026
Source repository:
- Permalink: illusions-lab/MDI@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Branch / Tag: refs/heads/main
- Owner: https://github.com/illusions-lab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yml@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Trigger Event: workflow_dispatch

File details

Details for the file illusion_markdown-2.0.5-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: illusion_markdown-2.0.5-cp310-abi3-macosx_10_12_x86_64.whl
Upload date: Sep 7, 2026
Size: 974.3 kB
Tags: CPython 3.10+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for illusion_markdown-2.0.5-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`192c7379b4a24d7c12c0b1ae4a22075e223cc1033286ce0a4774531e873ca1dd`
MD5	`ab9021176ac98ce3df1d675e661b6c0f`
BLAKE2b-256	`c30905f3daf5e1d1f42630bdcce40bfb69fd13200653aca6aae91f764733db52`

See more details on using hashes here.

Provenance

The following attestation bundles were made for illusion_markdown-2.0.5-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release-pypi.yml on illusions-lab/MDI

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: illusion_markdown-2.0.5-cp310-abi3-macosx_10_12_x86_64.whl
- Subject digest: 192c7379b4a24d7c12c0b1ae4a22075e223cc1033286ce0a4774531e873ca1dd
- Sigstore transparency entry: 2746692047
- Sigstore integration time: Sep 7, 2026
Source repository:
- Permalink: illusions-lab/MDI@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Branch / Tag: refs/heads/main
- Owner: https://github.com/illusions-lab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release-pypi.yml@0f67680d59e49091aa5d01b868a35ed5f67eb186
- Trigger Event: workflow_dispatch

Release history Release notifications | RSS feed

This release

2.0.5 This release

Sep 7, 2026 5 files

Jul 23, 2026 5 files

Jul 20, 2026 5 files

Jul 20, 2026 5 files

Jul 20, 2026 5 files

illusion-markdown 2.0.5

illusion-markdown

Install

Quick start

API

Platform support

Development

License

Automatic warichu presentation layout

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed