Crate asciidoc_parser

Expand description

§AsciiDoc parser for Rust

This is an effort to write a semantic parser for the AsciiDoc language in the Rust language.

As of October 2025 this crate is ready for experimental projects, but still has significant gaps in language coverage that render it not yet suitable for production applications. I don’t list work items that I’ve not yet started; work items that are partially implemented are documented with the to do tag in GitHub. Follow that for the most current status for planned development.

You’re welcome to follow along and contribute with the understanding that I may or may not drive this project a mature (1.0) release.

§Why do this?

Most of all this is a fun project and exercises architectural and project design skills that are different from my day job. As part of that work, I write technical standards for the Creator Assertions Working Group in Asciidoc and Antora.

Once the parser is sufficiently built out, I have a few projects I’d like to build out that depend on it:

A version of Antora that highlights differences between versions of a spec/document, as in version to version or proposed updates in a pull request.
A version of Antora or similar that shows what portions of a spec are tested/completed/known good. (See the following section on “spec-driven development.”)
A version of Zola, the static site generator that I use for most of my web sites, that accepts Asciidoc formatted text as input. (See Project proposal: Asciidoc support in Zola.)

For now I’m still driving the parser to being complete enough for those projects to start.

§Spec-driven coverage

(aka Why is the code coverage so low?)

If you know me from other projects, you know that I value high code coverage and that isn’t changed here, despite what the Codecov badge above might say.

With this project, I’m doing an experiment in what I call “spec-driven development.” That means not only am I monitoring coverage of the code (which is typically above 99%) but also coverage of the spec.

I’m reading page-by-page, line-by-line, and writing tests to verify that the implementation matches the specification(*). This slows progress considerably, but I expect it to result in an implementation that is very solid once complete. I’ve started tracking bugs found via this approach with the tag #sddbugfind. There are many already since I started tracking in August 2025.

(*) Yes, I’m aware that the Asciidoc language authors consider this a “language description,” not a specification. Since I’m experimenting with and potentially introducing the term spec-driven development as a broader term, I’m splitting the difference here.

§No planned support for some AsciiDoc features

The following features are supported in the Ruby implementation of Asciidoctor, on which this project is based, but are not supported – and will likely never be supported – in this crate:

Parsing UTF-16 content is not supported. (UTF-16 documents must be re-encoded to UTF-8 prior to parsing with this crate.)
Document types other than article are not supported. Specifically, features which are enabled for the book doctype are not supported.
The document attribute compat-mode is not supported.
The parser has built-in support for HTML5 rendering similar to what is provided in Asciidoctor. Other back ends could be supported by other crates by implementing the InlineSubstitutionRenderer trait. They will not be directly supported in this crate.
Setting document attributes via the inline attribute entry syntax is not supported. (Note that this syntax is discouraged and may eventually be removed from the AsciiDoc language documentation.)
Retrieving include file content via URL is not directly supported. An implementation could implement the IncludeFileHandler trait to provide that behavior.

§Licenses

The asciidoc-parser crate is distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT.

Note that some components and dependent crates may be licensed under different terms; please check the license terms for each crate and component for details.

IMPORTANT: This project is a personal project; it is known to my team at Adobe, but it is not an officially-sponsored project in any way.

§License for AsciiDoc language materials

IMPORTANT: This repository contains a snapshot of the AsciiDoc language description which comes with its own license terms. It is not the purpose of this repository to supplant or replace that description; these documents are here as part of tooling to ensure that this crate follows the language description as closely as possible. Please consult AsciiDoc Language @ Eclipse GitLab for the official language description.

The following applies to content in the asg and spec folders:

The AsciiDoc Language and the accompanying materials are made available under the terms of the Eclipse Public License v 2.0 (EPL-2.0). See LICENSE to find the full license text.

The following applies to content in the docs folder:

The user documentation for the AsciiDoc Language, located in the docs/ folder, is made available under the terms of a Creative Commons Attribution 4.0 International License (CC-BY-4.0).

Re-exports§

pub use document::Document;
pub use parser::Parser;

Modules§

attributes: Element attributes are a powerful means of controlling the built-in settings of individual block and inline elements in the AsciiDoc syntax. They can also be used to add supplemental information, such as citation metadata and fallback content, to certain elements.
blocks: Block elements form the main structure of an AsciiDoc document, starting with the document itself.
content: Describes the content of a non-compound block after any relevant substitutions have been performed.
document: Describes the top-level document structure.
parser: The Parser struct and its related structs allow a caller to configure how AsciiDoc parsing occurs and then to initiate the parsing process.
strings: String types that facilitate parsing.

Structs§

Span: Represents a subset of the overall UTF-8 input stream.

Traits§

HasSpan: Any syntactic element can describe its location within the source material using this trait.