Aozora Flavored Markdown

🧪 API reference · 🎨 Playground · 📦 Releases & binaries · 📝 Changelog

Aozora Flavored Markdown is a Markdown dialect, modelled after GFM, that layers Aozora Bunko (青空文庫) typography — ruby, bouten, 縦中横, ［＃…］ annotations, gaiji, accent decomposition — on top of CommonMark + GFM.

It is a superset of CommonMark + GFM, and which superset is a constructor: Options::commonmark() renders the CommonMark 0.31.2 spec suite verbatim, Options::gfm() renders the GFM 0.29 spec suite with all four extensions on at once, and Options::default() is the Aozora dialect — GFM + 青空文庫記法 + hardbreaks. Both suites run whole rather than a corner each: nothing is skipped, and the examples the 0.29 fixture states differently from the spec version that supersedes it are pinned to that later authority instead of excluded.

default() is the one that is not a strict superset, and deliberately so: hardbreaks turns every source newline into a <br>, because verse and dialogue boundaries are load-bearing in 青空文庫 source. Take it off with Options::default().with_hardbreaks(false) and the Aozora extensions kick in only where the input uses them, across both spec corpora swept whole. One reservation is left, and it is about input no CommonMark document has: the five private-use codepoints this crate substitutes one per 青空文庫 construct are not source text, so a source that types U+E001–U+E004 gets U+FFFD back from a render. The file extension stays .md.

CommonMark also owns rule rows at every width. In particular, a long - or = row directly below prose is a setext heading underline, not an Aozora-specific decorative separator. The real-corpus compatibility measurement behind that choice is in ADR-0027.

None of these claims is a promise, and this page deliberately states none of the counts. They live on the crate page alone, because that is the one document inside the package whose src/conformance.rs measures them: every figure there is formatted from a live run of both spec corpora, so the page cannot disagree with what the suite renders. A second copy here could, and did. tests/render_commonmark_superset.rs sweeps the same corpora through the dialect and holds the claim above. The conformance suites run with the workspace tests and coverage on every PR.

CommonMark  ──▶  GFM  ──▶  Aozora Flavored Markdown
commonmark()     gfm()     default()

What you can write

# 第一章                              (Markdown heading)
第一篇［＃「第一篇」は大見出し］      (Aozora heading, aliased to the same AST)

彼は｜青梅《おうめ》に行った。        (Ruby)
可哀想［＃「可哀想」に傍点］な人。    (Bouten / emphasis dots)
それは≪強調したい≫ことだった。      (Double angle quote, shown as 《…》)
昭和20［＃「20」は縦中横］年。        (Tate-chu-yoko)

［＃ここから字下げ］                  (Block indent)
段落……
［＃ここで字下げ終わり］

Quickstart

CLI:

cargo install aozora-flavored-markdown-cli --locked
aozora-flavored-markdown render input.md
aozora-flavored-markdown fmt --check input.md

Pre-built binaries for Linux x86_64, macOS arm64 and Windows x86_64 are attached to every release, with SHA256SUMS alongside.

Library:

cargo add aozora-flavored-markdown

use aozora_flavored_markdown::{Options, render};

let rendered = render("彼は｜青梅《おうめ》に行った。", &Options::default());
assert!(rendered.html.contains("<ruby>"));

The rendered HTML carries stable aozora-md-* CSS classes (classes::all, ADR-0011); the drop-in themes that style them ship as theme::{HORIZONTAL_CSS, VERTICAL_CSS} under the default-off theme feature, editable as plain CSS in crates/aozora-flavored-markdown/theme/. Full API docs are on docs.rs; runnable snippets live under crates/aozora-flavored-markdown/examples/.

Guarantees

• CommonMark / GFM compatibility, measured — both spec suites run whole under Options::commonmark() and Options::gfm(), nothing skipped; the counts are on the crate page.
• Aozora Bunko compatibility target — every notation listed at https://www.aozora.gr.jp/annotation/ parses, and no unconsumed ［＃ marker reaches the rendered HTML.
• Single binary, no runtime process dependencies.
• Zero parse-time hooks in comrak — it is an unmodified crates.io dependency. Aozora recognition lives in the sibling P4suta/aozora crate and is spliced into the comrak AST here.

Development

The supported development environment is the native, lockfile-backed mise toolchain (ADR-0026). Install mise, trust this repository's configuration, and install the exact resolved tools:

mise trust
mise install --locked
just test              # workspace tests through cargo-nextest
just ci                # the same five fixed suites GitHub Actions runs

just with no arguments lists every recipe. See CONTRIBUTING.md for the workflow and docs/adr/ for the architectural decisions.

Sibling repositories

Repo	What it is
P4suta/aozora	Pure 青空文庫記法 parser (aozora), its CLI (aozora-cli, which carries the formatter and the language server) and the tree-sitter-aozora grammar. Aozora-only test surfaces — the conformance vectors and the corpus sweep — live there, as do the authoring tools absorbed from the archived aozora-tools.

Security

Vulnerabilities go through GitHub Security Advisories — see SECURITY.md.

License

Dual-licensed under Apache-2.0 OR MIT. See NOTICE for the full third-party attribution index.