Dev-Centr Documentation

Dev-Centr documentation hub. Antora site aggregating dev-centr projects.
Explore the docs »

Report Bug · Request Feature

About The Project

This repository contains the Antora playbook and configuration for the Dev Center documentation site. It aggregates content from multiple sources to build a unified documentation portal.

Project Structure

File	Description
antora-playbook.yml	Production Antora playbook. Uses remote GitHub URLs for all content sources and the published UI bundle. Used by CI/CD.
antora-playbook-local.yml	Local sibling-repo playbook (committed). Expects content repos as siblings (see the playbook sources list: ../devcentr, ../switchyard, ../msi-generator, …).
antora-playbook.testing.yml	Same local content sources, but points ui.bundle at ../valentus-theme/build/ui-bundle.zip for theme work.
supplemental-ui/	Site overlay on the valentus-theme 2.x UI bundle: custom domain CNAME, accent-token brand CSS, header logo under img/, and a thin head-meta.hbs fork (FOUC paint-hold + preference boot scripts vendored from Valentus, plus the brand stylesheet link). Header logo / navbar text use playbook site.keys.
.vscode/	VS Code folder settings and extension recommendations for this playbook repo.
package.json	Defines dependencies and build scripts.

Documentation layout (docs/ first)

All documentation in this repo lives under a docs/-style Antora component root. Antora defines one component per start_path: everything under a start path is a single component, so a second component cannot be nested inside docs/.

| Path | Component | What lives there | docs/ | home | This repo’s own component: docs/antora.yml plus docs/modules/ROOT/{nav.adoc,pages/…} (portal Overview, Where Documentation Lives, Todo & Roadmap, Changelog Index, Docs site). | tools-docs/ | tools | Hub-owned descriptor for the synthetic Tools aggregate component. Many product repos declare name: tools in their own docs/; Antora merges same-name descriptors last-source-wins, so this source is listed last in every playbook and its antora.yml nav: lists every tool module’s nav. This repo contributes only the ROOT start page (tools-docs/modules/ROOT/pages/index.adoc). | platforms-docs/ | platforms | Same pattern for the Platforms aggregate (devcentr + devcentr-org modules from their own repos). Listed last among platforms sources for the same last-wins reason. | supplemental-ui/ | — | Hub overlay on the Valentus UI bundle (brand CSS, vendored SoftNav + site-nav-tree companion JS, partials, helpers). | lib/, scripts/, test/ | — | Hub-local Antora extension, diagram/maintenance scripts, and Node tests.

Why tools-docs/ and platforms-docs/ are not inside docs/: folding them into docs/ would merge them into the home component — Antora has no nested component descriptors. They are the documented exception to the house rule "all documentation under docs/`" (skill `antora-org-site); each still follows the standard internal modules/<MODULE>/… layout. There is deliberately no modules/ tree at the repo root: no playbook start_path points there, so anything placed there would look published but never build.

Playbooks: antora-playbook.yml (production, remote sources), antora-playbook-local.yml (sibling checkouts), and antora-playbook.testing.yml (same local sources with a locally built Valentus UI bundle — kept for local experimentation and fast theme dev loops; not used by CI).

back to top

Installation

Prerequisites

Dependency	Notes
Node.js	LTS recommended
pnpm	Package manager for install and build scripts

Install the required dependencies using pnpm:

pnpm install

back to top

Usage

Getting Started (Local Development)

Clone the content repos as siblings of this playbook repo (see antora-playbook-local.yml), start local Kroki (Mermaid companion), then build:

pnpm kroki:up
pnpm build

Local and CI Antora playbooks share kroki-server-url: http://127.0.0.1:8000 (see docker-compose.kroki.yml and .github/workflows/deploy.yml).

Testing Local Plugins / UI

Build the local UI bundle in a sibling valentus-theme checkout, then:

pnpm build:testing

Production / CI Build

To build with remote sources (same Kroki URL as local; start Kroki first, or rely on CI service containers):

pnpm kroki:up
pnpm run build:online

The output will be generated in the build/site directory (or as configured in the playbook).

Command	Purpose
pnpm install	Install dependencies
pnpm kroki:up / pnpm kroki:down	Start/stop local Kroki+Mermaid (docker-compose.kroki.yml)
pnpm build	Build site with local playbook (antora-playbook-local.yml)
pnpm build:testing	Build with testing playbook (e.g. local UI bundle)
pnpm run build:online	Build with remote sources (production/CI)

back to top

Development

This project is best managed by opening the repository folder in VS Code:

1. Open this repository folder in VS Code (File → Open Folder).

2. Ensure the recommended extensions are installed (AsciiDoc, YAML, etc.).

3. Use the integrated terminal for running builds.

Related

• Antora UI branding — teal chrome and logo keys

• Live docs site

Contact

DevCentr.org — support@devcentr.org

• Project: https://github.com/dev-centr/docs

• Site: https://docs.devcentr.org

back to top

Changelog

See Changelog.