Docs as Code Reference

Curated reference for documentation-as-code patterns used in the Domus ecosystem.

Related Documentation

Resource Description

AsciiDoc Mastery

Complete AsciiDoc reference from daily essentials to expert techniques. Progressive learning guide covering attributes, conditionals, substitutions, includes, tables, STEM math, and community contribution.

D2/AsciiDoc/Unix Mastery

Advanced patterns combining D2 diagrams, AsciiDoc, and Unix tooling for documentation workflows.

Antora Multi-Repo

Validated design for multi-repository documentation aggregation with Antora.

AsciiDoc Standards

Domus-specific AsciiDoc conventions and style guide.

D2 Diagrams

Validated design for D2 diagram integration in documentation.

Documentation Hub Setup

Runbook for setting up the documentation aggregation system.
New to AsciiDoc? Start with Level 1: Daily Essentials in the AsciiDoc Mastery guide.

AsciiDoc Basics

Document Header

= Document Title
:description: Page description for SEO
:navtitle: Short Nav Title
:keywords: comma, separated, keywords
:author: Your Name
:revdate: 2026-02-12
:icons: font

Headings

= Document Title (Level 0)
== Section (Level 1)
=== Subsection (Level 2)
==== Sub-subsection (Level 3)

Text Formatting

Format Syntax Result

Bold

*bold*

bold

Italic

_italic_

italic

Monospace

`code`

code

Highlight

#highlight#

highlight

Subscript

H~2~O

H2O

Superscript

E=mc^2^

E=mc2

Lists

Unordered

* Item 1
* Item 2
** Nested item
*** Deeper nested

Ordered

. First
. Second
.. Nested
... Deeper

Description List

Term 1:: Definition 1
Term 2:: Definition 2

Checklist

* [x] Completed task
* [ ] Pending task
* [*] Also completed (alternate)

Admonitions

NOTE: Informational note.

TIP: Helpful tip.

IMPORTANT: Important information.

WARNING: Warning message.

CAUTION: Danger zone.

Renders as:

Informational note.
Helpful tip.
Important information.
Warning message.
Danger zone.

Block Admonition

[NOTE]
====
Multi-line note with:

* Lists
* Code blocks
* Any content
====

Source Code Blocks

Basic

[source,bash]
----
echo "Hello World"
----

With Title

.Script example
[source,bash]
----
#!/bin/bash
echo "Hello"
----

With Callouts

[source,bash]
----
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \  (1)
  -d '{"key": "value"}' \  (2)
  https://api.example.com/endpoint
----
<1> Authentication header
<2> JSON payload

Inline Code

Run `netapi ise mnt sessions` to view sessions.

Tables

Basic Table

|===
|Header 1 |Header 2 |Header 3

|Cell 1
|Cell 2
|Cell 3

|Cell 4
|Cell 5
|Cell 6
|===

With Column Widths

[cols="1,2,3"]
|===
|Narrow |Medium |Wide

|A |B |C
|===

With Options

[cols="1,2",options="header,footer"]
|===
|Name |Value

|Foo |Bar
|Baz |Qux

|Total |All
|===

Cell Formatting

[cols="1,1,1"]
|===
|Left |Center |Right

|Left aligned
^|Centered
>|Right aligned

3+|Spanning all 3 columns

.2+|Row span
|Normal
|Normal

|Also normal
|Also normal
|===

Collapsible Blocks

.Click to expand
[%collapsible]
====
Hidden content here.

Can include any AsciiDoc content:

* Lists
* Code blocks
* Tables
====

Renders as:

Click to expand

Hidden content here.

Can include any AsciiDoc content:

  • Lists

  • Code blocks

  • Tables

Links and Cross-References

External Links

https://example.com[Link Text]

https://example.com[Link^] <-- Opens in new tab

Internal Cross-References (Same Component)

xref:page.adoc[Link Text]
xref:folder/page.adoc[Link Text]
xref:page.adoc#section-id[Link to Section]

Cross-Component References (Antora)

xref:component::page.adoc[Link Text]
xref:component:module:page.adoc[Link Text]
xref:infra-ops::runbooks/backup-strategy.adoc[Backup Strategy]

Anchors

[[custom-anchor]]
== Section with Custom Anchor

Link to it: <<custom-anchor,Section>>

Includes (Antora)

Include a Partial

include::partial$header.adoc[]

Include an Example File

[source,bash]
----
include::example$script.sh[]
----

Include with Tags

include::example$script.sh[tags=main]

In the source file:

# tag::main[]
echo "This part gets included"
# end::main[]

Include Lines by Range

include::example$script.sh[lines=5..20]

Antora Resource Locations

Prefix Directory

partial$

modules/ROOT/partials/

example$

modules/ROOT/examples/

attachment$

modules/ROOT/attachments/

image$

modules/ROOT/images/

Images

Block Image

image::diagram.png[Alt text]
image::diagram.png[Alt text,width=600]

Inline Image

Click the image:icon.png[icon,20] button.

From Antora Images Directory

image::diagrams/network-topology.svg[Network Diagram]

Diagrams as Code

D2

[d2,my-diagram,svg]
----
client -> server: request
server -> database: query
database -> server: results
server -> client: response
----

D2 Shapes

# Basic shapes
rectangle: Rectangle
oval: Oval {shape: oval}
cylinder: Database {shape: cylinder}
cloud: Cloud {shape: cloud}
hexagon: Hexagon {shape: hexagon}

# Connections
rectangle -> oval: arrow
oval <-> cylinder: bidirectional
cylinder -- cloud: line (no arrow)
cloud -> hexagon: labeled arrow {
  style.stroke-dash: 3
}

D2 Containers

network: Network Layer {
  firewall: Firewall
  router: Router

  firewall -> router
}

application: Application Layer {
  web: Web Server
  api: API Server

  web -> api
}

network.router -> application.web

D2 Styling

server: Server {
  style: {
    fill: "#0077B6"
    stroke: "#023E8A"
    font-color: white
    border-radius: 8
  }
}

Mermaid

[mermaid]
----
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
----

Mermaid Sequence Diagram

sequenceDiagram
    participant C as Client
    participant S as Server
    participant D as Database

    C->>S: Request
    S->>D: Query
    D-->>S: Results
    S-->>C: Response

Mermaid Class Diagram

classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog

PlantUML

[plantuml,sequence,svg]
----
@startuml
Client -> Server: Request
Server -> Database: Query
Database --> Server: Response
Server --> Client: Response
@enduml
----

Graphviz (DOT)

[graphviz,network,svg]
----
digraph G {
    rankdir=LR;
    node [shape=box];

    client -> firewall -> server -> database;
}
----

Attributes and Variables

Define Attributes

:project-name: Domus Digitalis
:version: 2026
:dc-ip: 10.50.1.50

The {project-name} version {version} connects to {dc-ip}.

Conditional Content

This shows everywhere except GitHub.

Unset Attribute

:!toc:

Sidebar and Quotes

Sidebar

****
This is a sidebar block.

Can contain any content.
****

Quote

[quote, Author Name, Source]
____
This is a quote block.
Multiple lines supported.
____

Verse (Preserves Line Breaks)

[verse, Author, Title]
____
Line one
Line two
Line three
____

Keyboard and Menu Macros

Press kbd:[Ctrl+C] to copy.
Select menu:File[Save As > PDF].
Click btn:[OK] to confirm.

Renders as:

Press Ctrl+C to copy. Select File  Save As  PDF. Click OK to confirm.

Passthrough (Raw HTML)

++++
<div style="color: red;">
  Raw HTML content
</div>
++++

Comments

// Single line comment (not rendered)

////
Multi-line comment block.
Nothing here is rendered.
////

Antora Component Structure

docs/
├── antora.yml              # Component descriptor
└── modules/
    └── ROOT/
        ├── nav.adoc        # Navigation
        ├── pages/          # Content pages
        │   ├── index.adoc
        │   └── topic/
        │       └── page.adoc
        ├── partials/       # Reusable fragments
        ├── examples/       # Includable code
        ├── images/         # Images
        └── attachments/    # Downloadable files

antora.yml Example

name: component-name
title: Component Title
version: '2026'
start_page: index.adoc
nav:
  - modules/ROOT/nav.adoc

nav.adoc Example

* xref:index.adoc[Overview]
* Section Name
** xref:page1.adoc[Page 1]
** xref:page2.adoc[Page 2]
* Another Section
** xref:folder/page3.adoc[Page 3]

Build Commands

# Local build (filesystem paths)
make local

# Build with GitHub URLs
make site

# Deploy to Cloudflare Pages
wrangler pages deploy build/site --project-name=domus-docs

# Purge CDN cache
netapi cloudflare purge domusdigitalis.dev -y

Related Resources