@illusions-lab/mdi-to-html

MDI 2.0 specification · 日本語 README

MDI

Markdown tooling for Japanese typography
Ruby, tate-chu-yoko, boten, warichu, vertical writing, and more.

What is MDI?

illusion Markdown (MDI) is Markdown for Japanese publishing. It preserves the Markdown you already know while adding the typography that Japanese prose needs: ruby readings, tate-chu-yoko, boten, warichu, vertical writing, and page-aware output.

Write an .mdi document once, then render it as HTML, PDF, EPUB, DOCX, or text formats for platforms such as Kakuyomu, Narou, and Aozora Bunko. Ordinary CommonMark and GFM remain valid MDI, so you can introduce MDI features only where your document needs them.

# 春は曙

{東京|とうきょう}で第^12^話を読む。

One parser, written in Rust

mdi-core is the canonical Rust implementation of the MDI grammar. It parses CommonMark, GFM, YAML front matter, and MDI extensions into a versioned document IR, then provides deterministic HTML, TXT, EPUB, DOCX, and PDF renderers.

The language toolkits below call this same parser instead of reimplementing the grammar. That means an MDI document has consistent syntax, diagnostics, and rendering semantics everywhere it runs.

Language toolkits

Language	Toolkit	Documentation
Rust	mdi-core
JavaScript / TypeScript	nodejs/
Python	python/
Swift	swift/
Android / Kotlin	android/

Repository layout

Directory	Responsibility
mdi-core/	Rust parser, versioned IR, validation, serialization, and deterministic renderers.
nodejs/	JavaScript/WASM bindings, ecosystem adapters, CLI, and documentation.
python/	PyO3 binding to mdi-core.
swift/	UniFFI or C-ABI binding to mdi-core.
android/	Android Kotlin/JNI binding, native build scripts, and Android contract.
mdi-android-jni/	Android-only JNI façade over mdi-core.

Node.js packages

Package	Purpose
@illusions-lab/mdi	Primary typed JavaScript API backed by Rust.
@illusions-lab/mdi-core	Generated low-level WebAssembly bridge.
@illusions-lab/mdi-cli	Rust-backed command-line adapter.
@illusions-lab/mdi-to-pdf	Chromium layout adapter for Rust-rendered HTML.
@illusions-lab/mdi-remark, mdast-util-mdi	Rust-backed Unified ecosystem adapters.
@illusions-lab/mdi-to-hast, @illusions-lab/mdi-to-html, @illusions-lab/mdi-to-epub, @illusions-lab/mdi-to-docx	Legacy public compatibility adapters.
@illusions-lab/mdi-export-profile	Shared typed export-profile configuration.

Project status

Development

cd nodejs
pnpm install
pnpm build
pnpm test

cd mdi-core
cargo build
cargo test

Building the WASM bridge also requires the wasm32-unknown-unknown Rust target and wasm-pack; the Node workspace build runs it automatically. CI tests the Rust core on Linux, macOS, and Windows for x64 and ARM64, and runs the JavaScript integration suite including Chromium PDF output on Linux x64.

Releases

Package versions use <MDI spec version>.<package release number>; for MDI 2.0, releases begin at 2.0.1. Use a patch Changeset for ordinary releases. Merging to main makes GitHub Actions build and publish packages through npm Trusted Publishing (OIDC).

cd nodejs
pnpm changeset
pnpm version

For an MDI specification version bump, run pnpm bump-spec-version 2.1 from nodejs/.

Related project

• illusions-lab/milkdown-mdi — Milkdown editor plugins for MDI syntax and vertical-writing display.

License

MIT