AST/ASG Compilation Pipeline

Golem operates as a deterministic, compiler-grade document processing pipeline built on top of asciidoctrine and asciidoctype.

Pipeline Lifecycle

 Source .adoc File
       │
       ▼ [1. Parse] (asciidoctrine.parse_to_ast / Lark)
 Concrete Syntax Tree (AST)
       │
       ▼ [2. Resolve] (asciidoctrine.resolve_to_asg / Semantic Analysis)
 Abstract Semantic Graph (ASG Node Dictionary)
       │
       ▼ [3. Render] (asciidoctype.AsciiDoctypeRenderer / Chameleon ZPT)
 HTML5 Fragment (body_html)
       │
       ▼ [4. Layout Template] (skeleton.pt / TAL Slot Insertion)
 Full Static HTML5 Document (dist/*.html)

Pipeline Stages

Lark AST Parsing: asciidoctrine parses raw text into a lossless concrete syntax tree.
Semantic ASG Resolution: Resolves document attributes, include directives, callout numbering, cross-references, and footnote indexing into a clean Abstract Semantic Graph (ASG).
Node Rendering: asciidoctype renders each ASG block using dedicated Chameleon TAL templates.
Layout Integration: Golem injects page_title, site_title, body_html, nav_tree, nav_html, toc_html, custom_css, and custom_js into the theme's skeleton.pt.
Fine-Grained Cache Invalidation: During build planning, Golem triggers the golem_mark_stale hook, allowing themes and plugins to selectively invalidate cache for specific templates or document nodes based on metadata.

Core Dependencies

Golem's pipeline is assembled from focused, independently testable Python libraries:

Library	Role
`asciidoctrine`	Standards-compliant Lark AST parser and semantic ASG resolver.
`asciidoctype`	Template translation engine powered by Chameleon ZPT templates.
`asciidoctest`	Python test runner extracting and executing inline doctests from AsciiDoc blocks.
`chameleon`	Fast, compiled Zope Page Templates (ZPT) engine.
`pluggy`	Standard Python hook and plugin management system (same engine powering pytest).
`click`	Composable command-line interface toolkit.