STD-024: AsciiDoc Build Toolchain

STD-024: AsciiDoc Build Toolchain

Purpose

Defines the build workflow for all AsciiDoc content in data/ using domus-asciidoc-build. This is separate from Antora (docs/modules/) which has its own build pipeline via make.

Scope

All files in data/ that use domus-asciidoc-build/bin/build-adoc.sh — including but not limited to:

  • Quijote edición analítica

  • Bible study (Reina-Valera)

  • C programming curriculum

  • Investigations (d000, d001)

  • Correspondencia

  • Any standalone AsciiDoc not part of the Antora site

Build Command

~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh <file.adoc> <format> --theme <theme>

Formats

Format Usage

html

Browser viewing, sharing via URL

pdf

Print, sharing as file, reading on tablet

docx

Microsoft Word (for non-technical recipients)

Variant (HTML only)

build-adoc.sh file.adoc html --variant catppuccin

Theme Catalog (PDF)

Color Name Legacy Name Colors Use For

purple

royal

Deep purple #1a1625, magenta #9D4EDD/#E040FB

Sharing with tutors, professors, external audiences

blue

don-quijote

Catppuccin Mocha, blue #89b4fa

Quijote study guide

dark

catppuccin

Catppuccin Mocha general

General purpose dark

burgundy

creative

Burgundy #3C1518

Literature, DIS-* assets

navy

learning

Navy #1A1A2E

Education, LRN-* assets

orange

operations

Orange #E65100

Runbooks, OPS-* assets

green

reference

Green

Technical references, ARS-* assets

base

base

Neutral

Minimal/default

Theme files: ~/atelier/_bibliotheca/domus-asciidoc-build/themes/pdf/<name>-theme.yml

Document Architecture

All data/ content follows the thin shell → assembler → partials pattern:

project-directory/
├── main-file-edicion.adoc       # Thin shell — title, attributes, one include
├── partials/
│   ├── cap-NN-assembler.adoc    # Assembler — reading order, all includes
│   ├── 01-section-name.adoc     # Content partial — text + annotations
│   ├── 02-section-name.adoc
│   ├── ...
│   └── 99-leyenda.adoc          # Symbol legend (if applicable)
└── output/                      # Build artifacts (gitignored)
    ├── main-file-edicion.html
    └── main-file-edicion.pdf

Thin Shell (6 lines max)

= Document Title
:description: One-line description
:revdate: YYYY-MM-DD
:icons: font
:toc: left
:toclevels: 3

Unresolved include directive in modules/ROOT/partials/standards/STD-024-asciidoc-build.adoc - include::partials/assembler.adoc[]

Assembler

// Assembler: Document Name — reading order
// Included by: main-file.adoc

Unresolved include directive in modules/ROOT/partials/standards/STD-024-asciidoc-build.adoc - include::01-section.adoc[]

Unresolved include directive in modules/ROOT/partials/standards/STD-024-asciidoc-build.adoc - include::02-section.adoc[]

Unresolved include directive in modules/ROOT/partials/standards/STD-024-asciidoc-build.adoc - include::99-leyenda.adoc[]

Content Partial

Each partial contains the source text and annotations. Structure varies by domain:

Literary analysis (Quijote, Bible):

  • [quote] — original text

  • [sidebar] — léxico arcaico, análisis retórico/literario

  • [NOTE] — gramática, espacio para anotaciones

  • [IMPORTANT] — hallazgo principal

Investigations:

  • [source,bash] — commands with verify-before/change/verify-after

  • [cols] — context tables

  • .Title labels for copyable blocks

Build Patterns

Ad-Hoc Single File

Any .adoc file — no project structure, no assembler, no partials required. Point the tool at any file and it renders:

PDF
~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh /path/to/any-file.adoc pdf --theme purple
HTML
~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh /path/to/any-file.adoc html --variant catppuccin
DOCX (Word)
~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh /path/to/any-file.adoc docx
EPUB
~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh /path/to/any-file.adoc epub
All formats at once
~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh /path/to/any-file.adoc all --theme purple --variant catppuccin

Works for scratch notes, one-off documents, meeting notes, or any standalone .adoc. Output lands in output/ next to the source file.

Annotated Edition (with analysis)

Build the thin shell — includes assembler → partials → full annotated document:

~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh \
  data/d000/education/quijote-study/edicion/p1-cap-033/p1-cap-033-edicion.adoc \
  pdf --theme purple

Plain Text (for sharing the original only)

Build directly from the source text — no annotations:

~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh \
  docs/modules/ROOT/pages/education/literature/quijote/primera-parte/texto/texto-033.adoc \
  pdf --theme purple

Batch Build (multiple chapters)

for ch in 032 033 034 035; do
  ~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh \
    data/d000/education/quijote-study/edicion/p1-cap-${ch}/p1-cap-${ch}-edicion.adoc \
    pdf --theme purple
done

HTML for GitHub Pages

~/atelier/_bibliotheca/domus-asciidoc-build/bin/build-adoc.sh \
  data/d000/education/quijote-study/edicion/p1-cap-033/p1-cap-033-edicion.adoc \
  html --variant catppuccin

Output Location

Build output goes to output/ inside the source file’s directory. This directory is gitignored via **/output/ in the root .gitignore.

Distinction from Antora

data/ (this standard) docs/modules/ROOT/

Build tool

domus-asciidoc-build/bin/build-adoc.sh

make (Antora playbook)

Themes

PDF themes + HTML variants

Antora UI bundle (domus-antora-ui)

Output

Local output/ directory

build/site/ → Cloudflare Pages

Tracking

Age-encrypted or gitignored

Tracked in git, published to docs site

Purpose

Personal study, investigations, sharing

Published documentation