AsciiDoc Authoring & Partial Files Protocol

Golem supports full standards-compliant AsciiDoc across 39 node types, rendered through Chameleon ZPT templates.

Supported AsciiDoc Constructs

1. Admonition Blocks

Golem supports all 5 standard admonitions with distinctive, color-coded callout boxes:

[NOTE]
====
Informational note for helpful side details.
====

[TIP]
====
Pro-tip for efficiency or performance.
====

[IMPORTANT]
====
Essential requirement or critical design invariant.
====

[WARNING]
====
Cautionary warning against breaking changes or syntax errors.
====

[CAUTION]
====
High-risk warning for potential data loss or security issues.
====

2. Source Code & Callouts

Syntax-highlighted listings with numbered callouts:

[source,python]
----
import click1



@click.command()2


def hello():
    click.echo("Hello, Golem!")
----
<1> Import the click CLI framework.
<2> Decorate the function as a command entry point.

3. Structured Tables

Tables support explicit column widths, header alignment, and embedded formatting:

[cols="1,2,1"]
|===
| Command | Purpose | Default Port

| `golem serve` | Live-reload development server | `8000`
| `golem build` | Compile static site to `dist/` | N/A
|===

4. Mathematical Expressions (STEM)

Inline formulas and block equations:

Inline formula: stem:[E = mc^2]

[stem]
++++
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
++++

5. Description Lists & Footnotes

Hierarchical term-definition syntax and anchored footnotes:

AST:: Concrete Abstract Syntax Tree parsed by Lark.
ASG:: Semantic Abstract Semantic Graph resolved by `asciidoctrine`.footnote:[Named after the compiler intermediate representation.]

Partial Files Protocol (`_*.adoc`)

In large technical books and manuals, chapters are often split across reusable sub-units included into parent documents via include::path.adoc[].

Any file prefixed with an underscore (e.g. _header.adoc, _sidebar_notes.adoc, _footer.adoc) is treated as a Partial File.

No Standalone Compilation: Partial files are never compiled into standalone HTML files in dist/.
DAG Dependency Tracking: When a partial file is modified, Golem's incremental DAG compiler traverses .golem/cache.json and automatically rebuilds every parent document that includes it.