Rationale: Why Antora + AsciiDoc?

The Documentation Challenge

Technical documentation faces several challenges:

Version Management - Documentation must track with code versions
Modular Organization - Large projects need logical content separation
Consistency - Standards must be maintainable across teams
Single Source - Avoid duplication while supporting multiple outputs
AI-Friendly - Support AI-assisted generation and maintenance

Why Not Markdown?

While Markdown is popular, it has limitations for technical documentation:

Feature	Markdown	AsciiDoc
Semantic Markup	Limited	Extensive (admonitions, includes, attributes)
Cross-References	Manual linking	Built-in xref system
Content Reuse	Copy-paste	Include directives and partials
Metadata	Front-matter only	Rich document attributes
Diagrams	External tools	PlantUML/Kroki integration
Versioning	Manual	Antora manages versions

Feature

Markdown

AsciiDoc

Semantic Markup

Limited

Extensive (admonitions, includes, attributes)

Cross-References

Manual linking

Built-in xref system

Content Reuse

Copy-paste

Include directives and partials

Metadata

Front-matter only

Rich document attributes

Diagrams

External tools

PlantUML/Kroki integration

Versioning

Manual

Antora manages versions

Why Antora?

Antora is a multi-repository documentation site generator designed for technical documentation:

Multi-Repository Support

Antora aggregates documentation from multiple Git repositories:

Microservices - Each service has its own docs
Shared Components - Common documentation referenced across projects
Standards - This repository provides reusable standards

Version Management

Antora automatically generates versioned documentation:

Documentation branches track code versions
Multiple versions available simultaneously
Version selector in generated UI

Component-Based Architecture

Documentation is organized into components:

event-management-docs/    # Component 1
api-docs/                  # Component 2
standards/                 # Component 3 (this repo)

Each component can have multiple modules with logical organization.

Static Site Generation

Antora generates static HTML sites:

Fast performance
Easy hosting (GitHub Pages, S3, etc.)
No server-side dependencies
Full-text search support

Why AsciiDoc?

AsciiDoc provides semantic markup designed for technical writing:

Rich Content Blocks

[NOTE]
====
AsciiDoc supports admonitions: NOTE, TIP, IMPORTANT, CAUTION, WARNING
====

[source,java]

public class Example { // … }

Content Reuse

Include Directives:

include::example$authentication.java[]
include::partial$common-setup.adoc[]

Partials allow shared content across multiple pages without duplication.

Cross-References

Internal Links:

See xref:api-guide.adoc[API Guide] for details.
See xref:security:authentication.adoc[Authentication] in the security module.

Antora validates all cross-references at build time.

Document Attributes

Reusable Variables:

:product-version: 2.5.0
:api-url: https://api.example.com

Connect to {api-url} version {product-version}

Diagrams as Code

PlantUML Integration:

[plantuml,architecture-diagram,svg]

@startuml actor User User → Gateway : Request Gateway → Service : Process @enduml

Diagrams are versioned with documentation and generated at build time.

AI-Assisted Documentation

Both Antora and AsciiDoc support AI-assisted documentation:

Structured Format

AsciiDoc syntax is well-defined and parseable
Antora structure provides clear organization rules
Validation catches errors in AI-generated content

Reusable Standards

Generic templates in this repository
Project-specific guides in each repo
Clear conventions for AI agents to follow

Version Control

All documentation in Git
AI-generated content reviewable via pull requests
Changes tracked with commit history

Comparison to Alternatives

Tool	Pros	Cons	Use Case
Markdown + MkDocs	Simple, popular	Limited features, manual versioning	Small single-repo projects
Sphinx + RST	Powerful, Python ecosystem	Complex syntax, steep learning curve	Python projects
Docusaurus	React-based, modern UI	Markdown limitations, JavaScript-centric	JavaScript/React projects
Antora + AsciiDoc	Multi-repo, semantic markup, versioning	Steeper learning curve than Markdown	Enterprise, multi-component systems

Tool

Pros

Cons

Use Case

Markdown + MkDocs

Simple, popular

Limited features, manual versioning

Small single-repo projects

Sphinx + RST

Powerful, Python ecosystem

Complex syntax, steep learning curve

Python projects

Docusaurus

React-based, modern UI

Markdown limitations, JavaScript-centric

JavaScript/React projects

Antora + AsciiDoc

Multi-repo, semantic markup, versioning

Steeper learning curve than Markdown

Enterprise, multi-component systems

Real-World Benefits

For Developers

Documentation lives next to code
Familiar Git workflow
IDE support for AsciiDoc
Build validation catches errors

For Technical Writers

Semantic markup (not HTML)
Content reuse without duplication
Consistent structure across projects
Version management built-in

For AI Agents

Well-defined syntax rules
Clear structural conventions
Template-based generation
Validation feedback

For Organizations

Scalable across projects
Consistent standards
Professional output
Low maintenance overhead

Migration Path

Existing Markdown documentation can be converted:

Automated tools (Pandoc) for basic conversion
Manual review for AsciiDoc features
Incremental adoption - convert as you update

Conclusion

Antora + AsciiDoc provides:

Professional technical documentation
Multi-repository aggregation
Semantic markup for rich content
Version management out-of-the-box
AI-assisted documentation support
Long-term maintainability

These benefits outweigh the learning curve for teams creating serious technical documentation.