https://github.com/nlopes/acdc

AsciiDoc tooling in rust
https://github.com/nlopes/acdc

asciidoc rust tooling

Last synced: 5 months ago
JSON representation

AsciiDoc tooling in rust

• Host: GitHub
• URL: https://github.com/nlopes/acdc
• Owner: nlopes
• License: mit
• Created: 2024-09-28T21:40:26.000Z (almost 2 years ago)
• Default Branch: main
• Last Pushed: 2026-01-31T21:31:34.000Z (5 months ago)
• Last Synced: 2026-02-01T09:21:30.452Z (5 months ago)
• Topics: asciidoc, rust, tooling
• Language: Rust
• Homepage:
• Size: 3.71 MB
• Stars: 20
• Watchers: 2
• Forks: 2
• Open Issues: 4
• Metadata Files:
  • Readme: README.adoc
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

          
= acdc - AsciiDoc Parser & Converter

image:https://github.com/nlopes/acdc/workflows/Test/badge.svg[CI Status,link=https://github.com/nlopes/acdc/actions]

image:https://docs.rs/acdc-parser/badge.svg[docs.rs,link=https://docs.rs/acdc-parser]

image:https://img.shields.io/crates/v/acdc-parser.svg[crates.io,link=https://crates.io/crates/acdc-parser]

image:https://img.shields.io/badge/license-MIT-blue.svg[MIT licensed,link=https://github.com/nlopes/acdc/blob/main/LICENSE]

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

For architecture and design decisions, see link:./ARCHITECTURE.adoc[ARCHITECTURE.adoc].

== Quick start

[source,bash]

----

# Parse and convert AsciiDoc to HTML

cargo run --bin acdc -- convert document.adoc

# Run the test suite

cargo nextest run

----

See link:./acdc-cli/README.adoc[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 (early/experimental)

│   └── src/

│       ├── capabilities/    # LSP features (diagnostics, hover, definition)

│       └── 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

├── 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)

    └── terminal/           # Rich terminal output

----

== Tooling

* link:./acdc-cli[acdc-cli] - AsciiDoc processor (CLI)

* link:./acdc-editor-wasm[acdc-editor-wasm] - WASM live editor with syntax highlighting and preview

* link:./acdc-lsp[acdc-lsp] - Language Server Protocol implementation (early/experimental)

* link:./acdc-parser[acdc-parser] - AsciiDoc parser library

* link:./converters[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

* **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 link:./acdc-parser/README.adoc[acdc-parser README] for detailed feature support and list handling notes.

== Building & testing

[source,bash]

----

# Build all crates

cargo build --all

# Run tests with detailed output

RUST_LOG=error 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

[source,bash]

----

# Enable trace logging for grammar module

RUST_LOG=acdc_parser::grammar::document=trace cargo run --bin acdc -- convert file.adoc

----

=== Compare with reference implementation

[source,bash]

----

# 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

* https://asciidoctor.org[asciidoctor] - Reference implementation

* https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc documentation]

* https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-lang/-/blob/main/spec/outline.adoc?ref_type=heads[Language Specification]