AsciiDoc Language

The AsciiDoc language project defines and maintains the AsciiDoc Language Specification and Technology Compatibility Kit (TCK), its artifacts, and a writer-oriented language guide. The AsciiDoc Language Specification describes the syntax and grammar, Abstract Semantic Graph (ASG), Document Object Model (DOM) interfaces, referencing system, designated extension points, processing phases, and required integrations and behaviors. The TCK is used to verify and self-certify that an AsciiDoc processor implementation is compatible with this specification.

Specifically, the project scope includes the following matters:

• AsciiDoc language syntax / grammar (i.e., EBNF, ANTLR4, or similar)
  • Lexicon
  • Preliminaries / primitives (e.g., line-oriented, block, inline, macro, preprocessor directive, etc.)
  • Doctype-specific structures and required elements
  • Built-in attributes and reserved attribute namespaces
  • Designated file extension (.adoc)
  • Escaping mechanism
• TCK: Technology Compatibility Kit for verifying and self-certifying compliance of an AsciiDoc language processor
• ASG: an encoded form of the parsed document for use in developing a language-agnostic TCK (e.g., JSON)
• DOM API (interfaces only): language-agnostic, semantic representation of the structure, metadata, and content in the AsciiDoc document
• Parsing strategy / processing phases (preprocess, parse, convert)
• Extension Facility
  • Syntax extension points (e.g., custom block or macro)
  • Resolvers (e.g., path and attribute resolvers, ID generator)
  • Lifecycle interceptors (e.g., preprocessor, output processor, tree processor)
• Internal and external referencing system: (e.g., xrefs, includes, images)
• Mandatory integration adapters: syntax highlighter, STEM, docinfo, icons
• Expected converter behaviors (e.g., toc, ID generation, caption numbering, collapsible blocks)

In addition to the specification document and TCK, the project also provides the following:

• AsciiDoc Language guide for writers
• ASG schema for the TCK
• API documentation for the DOM