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

# 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-lsp/                 # Language Server Protocol implementation
│   └── src/
│       ├── capabilities/    # LSP features (completion, diagnostics, etc.)
│       └── state/           # Document and workspace state management
├── 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
└── converters/              # Output converters
    ├── html/               # HTML5 converter
    ├── manpage/            # Native roff/troff manpage output
    ├── terminal/           # Rich terminal output
    └── common/             # Shared converter utilities

Tooling

• acdc-cli - AsciiDoc processor (CLI)

• acdc-lsp - Language Server Protocol implementation for editor integration

• acdc-parser - AsciiDoc parser library

• converters - collection of AsciiDoc converters

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 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 hold for any input (proptest)

3. TCK tests: Check specification compliance

4. Integration tests: End-to-end conversion testing

Known limitations

• Table spanning: Row/column spanning not implemented

• Inline markup in code/links: Bold/italic inside code spans and link text not parsed

• Cross-file references: LSP and parser are single-file only

See acdc-parser README for detailed feature support and list handling notes.

Building & testing

# Build all crates
cargo build --all

# Run tests with detailed output
RUST_LOG=error cargo nextest run --no-fail-fast

# 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 trace logging for grammar module
RUST_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