Server Documentation Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Server Documentation Workflow is a specialized segment of the CircleCI Docs Static Site architecture designed to manage, build, and deploy documentation specifically for self-hosted CircleCI Server versions. This workflow integrates multi-version management through Antora, allowing the site to serve documentation for multiple server releases (e.g., v4.1, v4.6) simultaneously while maintaining a consistent user interface and navigation structure.
Sources: README.md:10-15, ARCHITECTURE.md:20-25, TECHNICAL_REFERENCE.md:144-150
Architecture and Component Integration
The workflow utilizes Antora’s component-based architecture to isolate server documentation from other documentation types like user guides or API references. Server-specific content is stored in versioned branches and organized into modules, including a ROOT module for primary navigation and configuration.
Component Structure
Each server version is treated as a distinct Antora component. The structure within the repository (specifically under docs/server-admin-* or archived paths) follows a standard pattern:
- antora.yml: Defines the component name, title, version, and navigation entry points.
- modules/ROOT/nav.adoc: Defines the hierarchical sidebar for that specific server version.
- modules/installation/pages/: Contains phase-based installation guides.
- modules/operator/pages/: Contains administrative and operational guides.
Sources: CONTENT_AUTHORING.md:15-30, ARCHITECTURE.md:44-55, archive/server 4.1/antora.yml
Build and Deployment Flow
The build process for server documentation requires a pre-processing step where server-specific branches are fetched from the repository before the static site generator runs.
The diagram shows the sequential steps required to include server documentation in the final build.
Sources: README.md:40-45, DEVELOPMENT.md:35-45, archive/scripts/fetch-server-branches.sh
Version Management
The workflow handles multiple server versions using Git branches and Antora's versioning system. This allows authors to maintain documentation for "Latest," "v4.1," and other archived versions in parallel.
Maintenance Scripts
To ensure the local development environment has access to all versioned server content, developers must run the fetch-server-branches.sh script.
| Script | Purpose | Implementation File |
|---|---|---|
fetch-server-branches.sh | Clones and updates server-4* branches for multi-version support. | archive/scripts/fetch-server-branches.sh |
gen-git-last-update-meta.sh | Generates metadata for "Last Updated" dates on server pages. | TECHNICAL_REFERENCE.md:146 |
Sources: README.md:43-45, TECHNICAL_REFERENCE.md:144-150, archive/scripts/fetch-server-branches.sh
Content Authoring for Server
Server documentation authors use AsciiDoc and must adhere to specific semantic guidelines. Content is categorized into four types: Tutorials, How-to Guides, Technical Reference, and Explanations.
Version-Specific Content
Authors use conditional attributes to manage content that applies only to specific server releases. This prevents documentation drift between versions.
ifeval::["{serverversion}" == "4.1"]
This content is specific to the v4.1 installation phase.
endif::[]
Sources: CONTENT_AUTHORING.md:195-205, TECHNICAL_REFERENCE.md:44-50
Navigation Mapping
The project maintains a cross-reference mapping (xref-mapping.json) to resolve links between different components, such as linking from a server administration page to a general orb usage guide.
The sequence illustrates how internal cross-references are resolved during the server documentation build.
Summary
The Server Documentation Workflow provides a robust framework for managing the lifecycle of CircleCI Server documentation. By leveraging Antora's versioning, specialized Gulp tasks, and automated branch fetching, the system ensures that complex installation and operator guides remain accurate across multiple product releases. This structure allows developers and technical writers to contribute to specific versions without compromising the integrity of the global documentation site.