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 playbook (also used locally). Remote GitHub URLs in git; @antora-supplemental/facto-stack registers antora-local-content-sources to rewrite remotes to local clones when markers exist (auto off in CI). Snapshot: build/.antora/antora-playbook-local.generated.yml.
antora-playbook.testing.yml	Local Valens theme bundle (../valentus-theme/build/ui-bundle.zip); legacy flat extensions for fast UI iteration.
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 + local — source resolution at build time), and antora-playbook.testing.yml (local Valens bundle for theme work; not CI).

Each content repo can advertise its clone with a stable marker at the repo root: .antora-source-id (see antora-local-content-sources). This hub repo includes one for dev-centr/docs.

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 content repos anywhere on your machine (hive layout under %code%/github.com/dev-centr/… works). Add each repo’s .antora-src-* marker (or rely on the hive path heuristic). Start local Kroki, 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 (antora-playbook.yml + local source resolution)
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.