ACDC - AsciiDoc Parser & Converter

Fast, correct AsciiDoc parser and converter written in Rust using PEG grammar.

For architecture and design decisions, see ARCHITECTURE.adoc.

Quick start

# Parse and convert AsciiDoc to HTML
cargo run --bin acdc -- convert document.adoc

# Inspect the lint command and available lint-level flags
cargo run --bin acdc -- lint --help

# Run the test suite
cargo nextest run

See acdc-cli README for all CLI options, backends, and feature flags.

Project structure

acdc/
├── acdc-cli/                 # Command-line interface
│   └── src/
│       └── main.rs           # CLI entry point
├── acdc-lint/                # Lint command support for recommended-practice checks
├── acdc-lsp/                 # Language Server Protocol server
│   └── src/
│       ├── capabilities/     # LSP features (diagnostics, hover, completion, rename, references, semantic tokens, …)
│       └── state/            # Document and workspace state (cross-file anchor index)
├── acdc-parser/              # Core parser and AST
│   ├── src/
│   │   ├── grammar/          # PEG grammar definitions
│   │   ├── model/            # AST data structures
│   │   ├── preprocessor/     # Include and conditional handling
│   │   └── proptests/        # Property-based testing
│   └── fixtures/             # Test fixtures
├── acdc-editor-wasm/         # WASM live editor (syntax highlight + preview)
└── converters/               # Output converters
    ├── core/                 # Shared traits (Processable, Visitor)
    ├── dev/                  # Development utilities (unpublished)
    ├── html/                 # HTML5 converter
    ├── manpage/              # Native roff/troff manpage output
    ├── markdown/             # Markdown converter (CommonMark & GFM)
    ├── pdf/                  # PDF output backed by the Rust Typst engine
    └── terminal/             # Rich terminal output

Tooling

• acdc-cli - AsciiDoc processor (CLI)

• acdc-editor-wasm - WASM live editor with syntax highlighting and preview

• acdc-lint - lint command support for AsciiDoc recommended-practice checks

• acdc-lsp - Language Server Protocol implementation

• acdc-parser - AsciiDoc parser library

• converters - collection of AsciiDoc converters (HTML, manpage, markdown, PDF, terminal)

• acdc-converters-dev - internal dev-only converter utilities (unpublished)

Architecture overview

Parser design

PEG-based

Uses the peg crate for grammar definition.

Two-pass inline processing

First identifies boundaries, then parses content.

Fail-fast

Stops on the first error by design.

Preprocessor

Handles includes and conditionals before parsing.

Testing strategy

1. Fixture tests compare against known good outputs.

2. Property tests verify invariants for generated input.

3. TCK tests check specification compliance.

4. Integration tests exercise end-to-end conversion.

Building & testing

Before running all-features checks, install the development prerequisites in CONTRIBUTING.md.

# Build all crates and features
cargo build --workspace --all-features

# Run tests with detailed output
cargo nextest run --no-fail-fast --all-features --all-targets

# Run clippy with pedantic lints
cargo clippy --all-targets --all-features -- --deny clippy::pedantic

# Run property-based tests
PROPTEST_CASES=1000 cargo test --package acdc-parser --lib proptests

Development workflow

Debug parser issues

# Enable CLI trace logging for the grammar module
ACDC_LOG=acdc_parser::grammar::document=trace cargo run --bin acdc -- convert file.adoc

Compare with reference implementation

# asciidoctor is our reference
asciidoctor -o file.asciidoctor.html file.adoc
cargo run --bin acdc -- convert file.adoc
diff -u file.asciidoctor.html file.html

Contributing

1. Use conventional commits (feat:, fix:, docs:, etc.).

2. Run the full test suite before committing.

Acknowledgments

• asciidoctor - Reference implementation

• AsciiDoc documentation

• Language Specification