| name | docouture-docs-internals |
| description | How a docouture Antora documentation site is put together: the playbook, the docs/antora.yml component descriptor, the four names that must agree, the ROOT+main default layout, promoting Guides/Reference to their own modules, the per-artifact-module strategy for a monorepo, and the home-page vs. content-page patterns. USE WHEN adding a page or module, renaming the site/component, deciding whether a section or artifact earns its own module, building a landing/home page, or diagnosing a site that builds with zero pages or fails with 'start page not found'. EXAMPLES: 'add a new module', 'rename this docs site', 'build a marketing home page', 'the site builds but has no pages', 'start page not found', 'should this artifact get its own module'. |
Site structure
This site was scaffolded by docouture new (@inditextech/docouture-cli). This skill covers the
pieces that make it hang together — where each name is set, how a page becomes reachable,
and the two page patterns (home vs. content) worth copying rather than reinventing.
reference/naming.md — the four names that must agree, and how to fix them when they
don't (docouture doctor checks this automatically).reference/page-patterns.md — the home-page block structure, the recurring content-page
shapes, the always-present ROOT + main layout, and how a site grows more modules
(promoted sections, or one per artifact in a monorepo).reference/antora-extensions.md — what @inditextech/docouture-antora-extensions (a
different kind of extension from the authoring blocks in docouture-writing-docs-pages)
provides: the module switcher, site footer, search index and llms.txt generation.
For AsciiDoc authoring itself — xrefs, admonitions, code blocks, this site's custom
blocks — see the docouture-writing-docs-pages skill. For which modules/pages a site
should have in the first place, see docouture-getting-started (new site) or
docouture-documenting-changes (an existing site gaining a new module/artifact).
The moving pieces
docs/
antora-playbook.yml site title, content source, UI bundle, asciidoc/antora extensions
antora-playbook.local.yml same shape, but content.sources[] is just `branches: HEAD` —
what `docouture dev` and PR verification build against, since a
PR/feature-branch checkout doesn't have `main` or a release tag
package.json name, devDependencies (docouture-cli, ui-bundle, the two extension
packages), the `build`/`dev` scripts
src/
antora.yml component descriptor: name, title, version, nav
modules/<module>/nav.adoc navigation tree, one per module
The whole starter template — package.json, both playbooks, the nested src/ — was
copied under this repository's own docs/, so antora-playbook.yml lives at
<repo-root>/docs/antora-playbook.yml and the component descriptor ends up one level
further down, at docs/src/antora.yml. That's why antora-playbook.yml's
content.sources[0] reads url: .. (this repo's root, one level up from docs/) and
start_path: docs/src.
docs/build/ (git-ignored) is generated output, not part of this tree — never edit
or delete it directly. If docouture dev is running, it owns that directory and
rebuilds it live on every save; a second, ad-hoc build into the same path (or clearing
it by hand) pulls the site out from under that running server.
Versioning
docs/antora.yml's version/prerelease fields are identical on main regardless of
which versioning mode this site uses (version: prerelease, prerelease: true) — what
differs is only which git refs antora-playbook.yml's content.sources[0] aggregates
from (tags: ['docs/stable'] vs. tags: ['docs/v*']). If this site was scaffolded with
--mode versioned, see the docouture-docs-versioning skill for cutting a release; a
standalone-mode site (the default) has no separate skill for this — docouture doctor
and the docouture-release.yml workflow are all that's needed.
