docouture turns a git repository into a themed Antora documentation site. It has no engine of its own — it wires together an existing content pipeline (Antora), a themed UI, two sets of build-time extensions, and a CLI that scaffolds and drives all of it. Each piece is independently replaceable: swap the UI bundle, drop an extension package, or skip the CLI and call Antora directly. The sections below cover each piece, then how a build actually strings them together.
The content pipeline: Antora
Antora aggregates AsciiDoc content from one or more git
repositories/refs into a single site, based on a playbook (antora-playbook.yml) and
one component descriptor (antora.yml) per documentation component. docouture
doesn’t replace Antora’s model — it generates a playbook and descriptor that already
point at the right things, and layers extensions on top. See
Antora’s own documentation for the model
itself, and Antora Playbook/
Antora Descriptor for what this site’s own copies of those two
files say.
The UI: a themed Antora UI bundle
@inditextech/docouture-ui-bundle is a themed fork of
antora-ui-default: Handlebars layouts and
partials, CSS built on this project’s own design tokens, and browser scripts for theme
switching, search, tabs, accordions and the on-page table of contents. Antora reads it
as a plain zip (ui.bundle.url in the playbook) — nothing about it is
docouture-specific from Antora’s point of view. See UI Bundle.
The extensions: two different seams
Two packages hook two different parts of the pipeline, registered under two different playbook keys:
-
@inditextech/docouture-antora-extensions(antora.extensions) — site-level behavior: it hooks Antora’s own site-generation pipeline to add things Antora doesn’t do on its own — the module switcher, the site footer, the search index,llms.txtgeneration, the Kroki/https://shiki.style[Shiki] prewarm steps, legacy URL redirects, and the/latest/alias. -
@inditextech/docouture-asciidoc-extensions(asciidoc.extensions) — page-level content: it hooks the Asciidoctor processor itself to add AsciiDoc syntax docouture sites can write that stock Asciidoctor doesn’t have —[tabs],[cards],[accordion],[feature-tabs],[cta], thelabel:/mono:macros, table/video sizing attributes, and the Kroki/Shiki block implementations.
Listing either package under the other’s key makes Antora log a warning and skip it — see Antora Playbook.
The CLI: scaffolding, not a build tool
docouture (@inditextech/docouture-cli) doesn’t build anything itself — docouture
build/dev are thin wrappers around Antora, and docouture publish resolves a
publish driver package (@inditextech/docouture-publish-<target>) from the site’s own
node_modules. What the CLI actually owns:
| Responsibility | Commands |
|---|---|
Scaffolding |
|
Build (wraps Antora, doesn’t replace it) |
|
Publishing (resolves a |
|
Version bookkeeping |
|
Diagnostics |
|
Re-syncing generated files |
|
See CLI.
How a build actually runs
Locally, docouture build/dev shells out to the site’s own npm run build
(antora --fetch antora-playbook.yml). Antora aggregates content from
content.sources[], applies asciidoc.extensions to every page, then runs
antora.extensions over the resulting site model, and the UI bundle renders it through
its Handlebars layouts.
In CI it’s the same pipeline through one of the workflows docouture new scaffolds,
differing only in which playbook they read and what happens after:
-
docouture-pr-verify.yml— every pull request, buildsantora-playbook.local.yml(HEAD only — no other ref is reachable from a PR checkout), then runs link checking. Never publishes. -
docouture-publish-prerelease.yml— every push tomainthat touches content, builds the realantora-playbook.yml, then callsdocouture-publish.yml(docouture publish <target>, pushing whatever lands atoutput.dir) to publish it. -
docouture-release.yml— cutting a release, tags the version, then also callsdocouture-publish.ymlfor the definitive post-release build.
See Publishing a documentation and Releasing a documentation for each workflow’s own triggers.