# A2ML Pandoc Reader, Writer, and Filter

## Summary

Custom Pandoc reader, writer, and Lua filter for A2ML (Attested Markup Language) — a structured document format for AI agent manifests and project metadata.

A2ML provides a typed, formally verified surface syntax with directives (`@abstract`, `@opaque`, `@fig`, `@ref`, etc.), sections, key-value metadata, and cross-references. This tooling brings full Pandoc ecosystem support: convert A2ML to HTML, PDF, DOCX, Markdown, EPUB, and dozens more formats.

## Components

- **a2ml.lua** — Combined Pandoc custom reader (360 lines). Parses A2ML surface syntax into the Pandoc AST preserving headings, directives, code blocks, inline formatting, and cross-references.
- **a2ml-reader.lua** — Standalone reader variant (189 lines) for simpler use cases.
- **a2ml-writer.lua** — Custom Pandoc writer (153 lines). Converts any Pandoc AST to valid A2ML output, enabling round-trip conversion and cross-format workflows.
- **a2ml-filter.lua** — Post-processing Lua filter with six passes: cross-reference resolution, `@include` directive expansion, TOC generation, diagram rendering (Mermaid/Graphviz), SPDX validation, and git metadata enrichment.
- **a2ml.html** — HTML5 Pandoc template with directive-specific styling (colour-coded borders for `@abstract`, `@opaque`, `@fig`, `@note`, `@warning`), responsive layout, print-friendly output, and syntax highlighting.

## Usage

```sh
# A2ML to HTML (full pipeline)
pandoc -f a2ml.lua input.a2ml \
  --lua-filter=a2ml-filter.lua \
  --template=a2ml.html \
  -o output.html

# A2ML to PDF
pandoc -f a2ml.lua input.a2ml -o output.pdf

# Markdown to A2ML
pandoc input.md -t a2ml-writer.lua -o output.a2ml
```

## Requirements

- Pandoc 3.0+ with Lua support

## Spec

- A2ML v1.0.0: <https://github.com/hyperpolymath/standards/tree/main/a2ml>
- Media type: `application/vnd.a2ml` (IANA registration pending)

## Related

- [pandoc/lua-filters](https://github.com/pandoc/lua-filters) — Community Lua filters repository
- [A2ML LSP server](../lsp/) — Language Server Protocol implementation
- [VS Code extension](../editors/vscode/) — Syntax highlighting for VS Code
- [A2ML specification](../SPEC-v1.0.adoc) — Full language specification

## License

PMPL-1.0-or-later (Palimpsest License)

## Author

Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
