Crate adoctra 

adoctra: umbrella crate. Re-exports the core editor/parse API and, behind feature flags, the native backends.

let result = adoctra::parse("= Hello\n\nWorld");
assert!(result.diagnostics.is_empty());
use adoctra::Backend;
let html = adoctra::html::HtmlBackend::new().convert(&result.document).unwrap();
assert!(String::from_utf8(html).unwrap().contains("<h1>Hello</h1>"));

Re-exports

pub use adoctra_html as html;

Modules

extension

The extension API (block, block macro and tree processors). Extension API: adoctra’s own processors at the points where Asciidoctor invokes its extensions (user decision 2026-11-05: an own Rust API, not Ruby API compatibility).

Structs

Attributes

Ordered map of document attributes. BTreeMap keeps output deterministic, which matters for snapshot/TCK testing.

Author

AuthorDetails

An author as the HTML header shows it (Document::authors): the effective name after replacements and the email after macros.

BinaryResource

Original resource bytes (an encoded include or an embedded image). content_type is a type the source reports (e.g. an HTTP Content-Type), if any.

Block

A block node: its source span, an optional id, and its kind.

BlockMacroRequest

A block macro handed to a BlockMacroProcessor.

BlockRequest

A block handed to a BlockProcessor.

DateTime

A wall-clock time with its UTC offset, as the host’s clock reports it.

Diagnostic

DiagnosticCursor

A logger cursor need not identify the physical span (selected includes and reader lookahead can change its file and line in the reference processor).

DiagnosticReport

Presentation overrides for conversion logs; never used to rewrite spans or remove editor diagnostics. Unspecified severity/text use the diagnostic’s.

Document

A whole parsed document: header attributes plus a sequence of blocks.

DocumentDates

The times behind Ruby’s fill_datetime_attributes: local is now (localdate, localtime, …), document the input’s modification time (docdate, doctime, …). A host honouring SOURCE_DATE_EPOCH passes that instant in UTC for both, and the current time as document when the input has no file.

DocumentHeader

Source declarations in a document header. Effective (possibly overridden) metadata lives in Document.attributes. The title remains the first level-0 heading in blocks, avoiding a second mutable copy of its inline tree.

ExtensionAttributes

Block attributes in Ruby’s insertion order (a Ruby Hash): metadata lines in reading order, then the keys the extension point adds (positional names, default attributes, cloaked-context). Setting an existing key keeps its position. A key can hold Ruby’s nil: an empty positional value ([,svg]) is a key without a value, and Ruby code that walks the hash (asciidoctor-diagram’s checksum) sees it.

IncludeLimits

Bounds for recursive resource expansion (the primary source is excluded).

IncludeResource

An include’s immutable decoded source. A finite line selection may recover an intact prefix when the unread tail cannot be decoded. The prefix starts at byte zero, so physical line numbers and decoded UTF-8 offsets stay valid.

MemoryResources

Application-owned resources in a virtual directory tree. Names use / on every platform; an initial slash addresses the virtual root. . and .. are normalized, but traversal above that root is rejected. No URL decoding, filesystem access or network access is performed.

NewBlock

A block created by a processor, with its attributes. title, caption, id, role, style, reftext and *-option keys become the block’s metadata; other named keys stay block attributes; positional keys are dropped.

OmittedSourceLine

A whole undecodable line excluded from an include snapshot. offset is the insertion point in its retained UTF-8 text; line is the original one-based physical line. Bytes include the original line ending, if any.

OmittedSourceSpan

A byte range within an omitted physical line, including neither an invented UTF-8 decoding nor a Unicode column. The source ID is the diagnostic’s.

OutputPaths

The output file and directory of a document converted for a file (Ruby’s outfile/outdir).

ParseOptions

ParseResult

The result of parsing for editor use: always succeeds, carries diagnostics.

ProcessContext

What a processor can see of the document and how it reports problems.

Registry

The processors a host registers for parsing.

Resource

ResourceError

ResourceRequest

A request after target attribute substitution. referrer is a canonical name returned by this same provider, or None for a top-level resource.

Revision

SourceFile

SourceId

SourceMap

SourcePosition

One-based line and Unicode scalar column (not a UTF-16 editor column).

Span

A byte range [start, end) in the original source.

SystemPath

A resolved path and the warnings Ruby logs while resolving it.

Token

Enums

AttrKey

A key of ExtensionAttributes: Ruby’s integer keys for positional values and string keys for named ones.

BlockContext

The context of the block a BlockProcessor replaces: the delimited block’s own context or a paragraph (Ruby’s cloaked-context).

BlockKind

Block-level element kinds.

ContentModel

How a BlockProcessor receives the block’s lines (Ruby’s content_model). The lines are always the preprocessed lines of the block (includes and conditionals applied).

DiagnosticLocation

DocinfoLocation

Where the converter places docinfo content.

Error

IncludeInput

Provider input awaiting the reader’s line/tag selection. Only UTF-8 and ASCII-8BIT defer validation; transcoding codecs validate consumed bytes.

Inline

Inline (phrase-level) elements. Every variant carries its source Span.

MacroContent

How a BlockMacroProcessor receives the text in its brackets.

NewBlockKind

The kind of block a processor creates. Text sources are split into lines with trailing whitespace removed, like Ruby’s Block.new with a string :source.

OutputTarget

The output location a host resolved before parsing (absolute paths, as Ruby’s normalize_system_path gives them).

ResourceErrorKind

SafeMode

Ruby’s SafeMode levels.

Severity

TokenKind

Constants

COMPATIBILITY_VERSION

Parse AsciiDoc source into a ParseResult (never fails on syntax). The Asciidoctor release whose behavior adoctra reproduces (compatibility/asciidoctor-version), exposed to documents as the locked asciidoctor-version attribute like Ruby’s Document#initialize.

Traits

Backend

BlockMacroProcessor

Handles name::target[attrlist] lines.

BlockProcessor

Handles a block whose style is its name.

ConversionStart

A converter’s work at the start of conversion. Ruby’s convert_document builds the head (reading a custom stylesheet, which can also activate the URI cache) after converting the document title and before the header outline and the body convert, so its reads and warnings precede those of the body’s images. Core converts the body while parsing, so a converter that reads resources in its head passes this hook to parse_resource_with_start or parse_with_start; core calls it once at that point and reports the returned warnings as conversion diagnostics there.

ResourceProvider

TreeProcessor

Runs on the finished document (after reading and conversion-time substitutions), before a backend converts it.

Functions

is_root_path

Ruby’s PathResolver#root? for this host: /x, and on Windows also C:/x, C:\x and \x.

parent_system_dir

Ruby’s File.dirname of a posixified absolute or relative path: the root (/, or C:/ on Windows) stays a root, a bare name gives ..

parse

parse_resource

Parse a registered snapshot, expanding includes through the supplied provider. Only an invalid primary id returns Err; include failures are diagnostics. If the provider supplies a ResourceProvider::document_path, it determines locked docfile, docdir, docname and docfilesuffix attributes for the primary document, overriding those keys in options.attributes.

parse_resource_with_start

parse_resource with a converter’s ConversionStart hook, called where Ruby’s converter starts the document (see the trait).

parse_with_options

Parse one source with its identity and hard attribute overrides. The caller retains the corresponding SourceMap; parsing performs no file I/O.

parse_with_start

parse_with_options with a converter’s ConversionStart hook.

posixify_path

Ruby’s PathResolver#posixify for this host: on Windows backslashes become slashes; elsewhere the path is unchanged.

resolve_system_path

Ruby’s PathResolver#system_path(target, start, jail, target_name:, recover:) for a host (e.g. a CLI resolving its output paths): start is absolute, jail (if any) absolute. With recover an escape from the jail is moved inside it with Ruby’s warnings; without it the result is Ruby’s SecurityError message, e.g. to_dir /x is outside of jail: /doc (disallowed in safe mode).

tokens

Tokenize AsciiDoc source for syntax highlighting.

tokens_resource

Highlight a registered document and its includes. Each token belongs to one original source; tokens crossing source boundaries are split into fragments.

tokens_with_options

Highlight one source using the same source identity and attribute options.

Type Aliases

ResourceResult

Result