Content Authoring Guide
Relevant source files
The following files were used as context for generating this wiki page:
The CircleCI Docs Static Site is a documentation platform built using Antora, designed to manage multi-repository technical documentation through a component-based architecture. This guide serves as the primary resource for authors and developers to understand how to create, organize, and format content using the AsciiDoc markup language.
The authoring process separates content (AsciiDoc files) from presentation (custom UI templates), allowing authors to focus on technical accuracy and clarity while the build system handles site assembly. Key architectural principles include modularity, separation of concerns, and extensibility through custom JavaScript extensions.
Sources: README.md:10-15, ARCHITECTURE.md:15-20
Content Organization and Architecture
The documentation is structured into logical components, each residing within its own directory under docs/. This modular structure allows for distinct versioning and navigation management per component.
Component Structure
Each documentation component follows a standardized Antora directory layout. This structure ensures that the build engine can correctly locate pages, partials, assets, and navigation definitions.
The diagram shows the standard hierarchy of an Antora component, starting from the configuration file down to individual page and asset directories.
Sources: CONTENT_AUTHORING.md:21-40, ARCHITECTURE.md:43-60, TECHNICAL_REFERENCE.md:144-160
Key Documentation Components
The site is divided into several primary functional areas:
| Component | Description | Path |
|---|---|---|
root | Home and landing pages | docs/root/ |
guides | How-to guides and tutorials | docs/guides/ |
reference | API and configuration references | docs/reference/ |
orbs | CircleCI orbs documentation | docs/orbs/ |
server-admin | Server administration guides | docs/server-admin-4.*/ |
contributors | Contributor guidelines | docs/contributors/ |
Sources: CONTENT_AUTHORING.md:12-20
Document Structure and Metadata
Every page in the system begins with a document header containing the title and specific metadata attributes that control the UI and search engine optimization (SEO).
Page Attributes and Headers
Attributes are defined at the top of an .adoc file using the :attribute-name: value syntax.
| Attribute | Purpose |
|---|---|
:description: | Used for SEO and meta descriptions |
:page-toclevels: | Controls the depth of the Table of Contents (e.g., 3) |
:page-layout: | Defines the Handlebars template used for rendering |
:page-badge: | Adds a visual status badge (e.g., Preview, Beta) to the title |
Sources: CONTENT_AUTHORING.md:66-75, CONTENT_AUTHORING.md:111-122
Status Badges
Authors can indicate the status of a feature using custom badges styled with Tailwind CSS classes.
= Feature Name
:page-badge: Preview
:page-badge-classes: text-white bg-orange-500 border border-orange-600
Sources: CONTENT_AUTHORING.md:84-88
AsciiDoc Syntax and Formatting
The system uses the AsciiDoc language to provide powerful formatting capabilities for technical content.
Admonitions
Admonitions are used to highlight critical information or provide helpful tips. The supported types are: NOTE, TIP, IMPORTANT, WARNING, and CAUTION.
Sources: CONTENT_AUTHORING.md:124-134
Code Blocks and Tabs
Technical documentation frequently requires code snippets and platform-specific instructions.
- Code Blocks: Delimited by
----and annotated with[source,language]for syntax highlighting. - Tabs: Managed by the
@asciidoctor/tabsextension to group related content.
The flow represents how the tabbed content extension processes separate blocks of information into a single interactive UI component.
Sources: CONTENT_AUTHORING.md:158-169, DEVELOPMENT.md:100-112
Cross-References and Navigation
Internal links use the xref macro. Links can span across components by specifying the component name.
- Internal Link:
xref:page-name.adoc[Text] - Cross-Component:
xref:component:page.adoc[Text] - Navigation: The
nav.adocfile defines the sidebar hierarchy using bulleted lists of xrefs.
Sources: CONTENT_AUTHORING.md:196-210, ARCHITECTURE.md:75-82
Content Authoring Workflow
The contribution process follows a standard developer workflow involving local previewing and peer review.
Development Workflow
Authors use a local development server to see live updates of their changes.
This sequence illustrates the interaction between the author's local environment and the automated build tasks during the writing process.
Sources: DEVELOPMENT.md:39-55, CONTRIBUTING.md:65-75
Review Checklist
Before submitting a Pull Request (PR), authors must verify:
- Document follows hierarchical structure guidelines.
- All
xrefcross-references resolve correctly. - Images are stored in
assets/images/and have alt text. - Navigation entries in
nav.adocare updated. - Code examples are verified for technical accuracy.
Sources: CONTENT_AUTHORING.md:244-255, CONTRIBUTING.md:132-145
Advanced Authoring and Extensions
The platform's functionality can be extended using custom JavaScript-based Antora extensions.
Custom Extensions
Extensions are located in the extensions/ directory and must be registered in the antora-playbook.yml. They can hook into various lifecycle stages, such as adding metadata or post-processing HTML.
Sources: DEVELOPMENT.md:175-185, ARCHITECTURE.md:109-122
Semantic Guidelines
- Voice: Use clear, concise language and the active voice.
- Direction: Address the reader as "you."
- Tense: Use present tense whenever possible.
- Content Types: Distinguish between Tutorials (learning), How-to Guides (tasks), Reference (specifications), and Explanations (concepts).
Sources: CONTENT_AUTHORING.md:225-240
Conclusion
The Content Authoring Guide provides a robust framework for managing complex technical documentation at scale. By leveraging Antora's component-based architecture and AsciiDoc's rich formatting, contributors can ensure that the CircleCI documentation remains accurate, maintainable, and highly navigable for all users.