pandoc-a2ml

Pandoc custom reader, writer, and filter for A2ML (Attested Markup Language) — converts .a2ml files to and from any Pandoc output format.

Table of Contents

• Overview
• Usage
• Related
• License

Overview

A2ML is the markup language used across the hyperpolymath estate for machine state files, AI manifests, and structured documentation. pandoc-a2ml lets Pandoc consume and produce A2ML directly, enabling conversion to HTML, PDF, DOCX, Markdown, or any other format Pandoc supports.

Three cooperating Lua components:

• a2ml-reader.lua — Pandoc custom reader. Parses A2ML surface syntax (Scheme-style comments, headings, directive blocks, fenced code, bullet lists) into Pandoc’s internal AST. Directive blocks (@name: …​ @end) become pandoc.Div elements with class a2ml-<name>.

• a2ml-writer.lua — Pandoc custom writer. Walks the Pandoc AST and emits valid A2ML surface syntax: headings (#), bullet lists (- `), fenced code blocks, and `@name: …​ @end directive blocks.

• a2ml-filter.lua — Six-capability Lua filter (three traversal passes): collects heading IDs and enriches metadata from git; resolves @ref(id) cross-references and @include(file.a2ml) inclusions; renders mermaid/graphviz diagrams; validates SPDX headers; generates a table of contents.

Usage

# A2ML → HTML
pandoc -f a2ml-reader.lua input.a2ml -o output.html

# A2ML → Markdown
pandoc -f a2ml-reader.lua input.a2ml -t markdown

# A2ML → A2ML (normalise)
pandoc -f a2ml-reader.lua input.a2ml -t a2ml-writer.lua -o output.a2ml

# With filter pipeline (cross-references, includes, ToC)
pandoc -f a2ml-reader.lua --lua-filter a2ml-filter.lua input.a2ml -o output.html

Related

• Pandoc custom readers

• Pandoc Lua filters

• pandoc-k9 — sibling reader/writer for K9 Nickel components

License

PMPL-1.0-or-later. See LICENSE.