Architecture Overview

Overview

libasciidoc processes AsciiDoc documents through a pipeline: parse the input into a document model, then render that model into the desired output format.

AsciiDoc text → Parser → Document Model → Renderer → HTML5 / XHTML5 / DOCX

Document Model

A document contains blocks, which can have attributes, nested blocks, and elements.

Blocks are of the following types:

  • Section

  • Paragraph

  • Delimited block

  • Image

  • Table

  • List

  • File inclusion

  • Comment

Tables, lists, and delimited blocks can contain other blocks.

Blocks can also contain inline elements:

  • Quoted text (bold, italic, monospace, etc.)

  • Links

  • Inline images

  • Passthrough text

  • Footnotes

  • User-defined macros

Attributes are set within square brackets ([]), both on top of document blocks and as a suffix of elements.

Major Components

Parser (internal/parser/)

The parser is generated from a PEG grammar and produces a "draft document" in which sections are not yet organized hierarchically, blocks are not attached to parent sections, blank lines are present, and document attribute declarations and substitutions have not been resolved. File inclusions are processed at this stage.

This draft document is then transformed into a "final document" in which sections are organized hierarchically with their child blocks attached. Document attribute substitutions have been resolved (sometimes producing new elements such as links), and blank lines have been stripped (except within delimited blocks).

Document Model (types/)

The types package defines the data structures that represent an AsciiDoc document: sections, paragraphs, lists, tables, inline elements, attributes, and metadata. This is the intermediate representation that both the parser produces and the renderers consume.

Renderers (internal/renderer/)

Each output format has its own renderer that walks the document model and produces output:

  • HTML5 — the default, produces standards-compliant HTML5 using Go text templates

  • XHTML5 — produces XHTML5 (self-closing tags, XML-compliant) using Go text templates

  • DOCX — produces Office Open XML (Word documents) by building the required ZIP parts (word/document.xml, relationships, styles, numbering, footnotes, and media) and writing WordprocessingML directly, with optional theme support

Configuration (configuration/)

The configuration package provides functional options for controlling how documents are parsed and rendered. It handles document attributes, backend selection, CSS, themes, and custom macros.

Static Site Generator (internal/site/)

The site generator builds a multi-page HTML website from a directory of AsciiDoc files. It handles navigation tree construction, page ordering via :weight: attributes, and layout templates.

CLI (internal/cli/)

The CLI package provides shared command-line flag parsing and dispatch logic used by both ascii2html and ascii2doc entry points.

Adding a New Feature

The typical flow for adding support for a new AsciiDoc element is:

  1. Add or modify the PEG grammar rule in the parser

  2. Add the corresponding type in the types package

  3. Implement rendering in each renderer (HTML5, XHTML5, DOCX)

  4. Add tests at each layer

Built with ascii2html