Navigation System
Relevant source files
The following files were used as context for generating this wiki page:
The Navigation System of the CircleCI Docs Static Site is a multi-layered framework designed to provide structural and interactive access to documentation content. It is built upon Antora, utilizing a component-based architecture where navigation definitions are decoupled from the UI presentation. The system manages hierarchical sidebars, breadcrumbs, version switching, and cross-references (xrefs) across multiple repositories and components.
Sources: ARCHITECTURE.md:10-15, README.md:12-18
Navigation Architecture
The system operates by combining file-based declarations with a dynamic UI engine. Navigation is defined at the module level and aggregated by the Antora generator into a site-wide tree.
Structural Components
| Component | Description | File/Location |
|---|---|---|
| Navigation File | AsciiDoc file defining the hierarchy of a specific module. | nav.adoc |
| Component Config | Defines which navigation files are included and the start page. | antora.yml |
| Xref Mapping | A JSON registry used to map slugs to specific component/module paths. | xref-mapping.json |
| UI Templates | Handlebars partials that render the navigation data into HTML. | ui/src/partials/ |
Sources: CONTENT_AUTHORING.md:231-240, ARCHITECTURE.md:46-55, TECHNICAL_REFERENCE.md:131-140
Content Hierarchy Flow
The following diagram illustrates how content moves from a raw AsciiDoc definition to a rendered UI component:
Navigation Syntax and Declaration
Navigation entries are defined using AsciiDoc's cross-reference (xref) syntax within nav.adoc files. This allows for deep linking between pages, modules, and even external components.
nav.adoc Definition
The hierarchy is created using asterisks (*) to denote levels.
*: Top-level category or page.**: Second-level nested page.***: Third-level nested page.
* xref:index.adoc[Getting Started]
** xref:installation.adoc[Installation]
*** xref:requirements.adoc[System Requirements]
** xref:configuration.adoc[Configuration]
* xref:advanced.adoc[Advanced Topics]
Sources: CONTENT_AUTHORING.md:231-240, ARCHITECTURE.md:58-63
Cross-References (Xrefs)
Internal links within the navigation system use the xref macro to ensure link integrity during the build process.
- Same Component:
xref:page-name.adoc[Link Text] - Different Component:
xref:component-name:page-name.adoc[Link Text] - Specific Section:
xref:page-name.adoc#section-id[Link Text]
Sources: CONTENT_AUTHORING.md:214-225, TECHNICAL_REFERENCE.md:144-150
Technical Implementation
UI Model Data Structure
The navigation tree is represented in the UI model as an array of items. Each item contains the content to display, the URL, and any nested child items.
navigation:
- root: true
items:
- content: Quickstart
url: '#'
urlType: fragment
items:
- content: Hardware Requirements
url: /xyz/5.2/index.html
urlType: internal
- content: Reference
items:
- content: Keyboard Shortcuts
url: '#'
urlType: fragment
Sources: ui/preview-src/ui-model.yml:68-95
Xref Registry Mapping
The system uses a mapping file (xref-mapping.json) to resolve short filenames to their full component and module paths. This is critical for maintaining links when content is moved between modules.
"managing-api-tokens": {
"component": "guides",
"module": "toolkit",
"filename": "managing-api-tokens.adoc"
}
Sources: archive/scripts/xref-mapping.json:302-306
Build and Serving Logic
The navigation system is built in stages during the site generation pipeline.
Navigation Components in the UI
- Sidebar (nav.hbs): Displays the hierarchical navigation defined in the current component's
nav.adoc. - Component Explorer: Allows users to switch between different documentation components (e.g., Guides vs. Server Admin).
- Breadcrumbs: Shows the current location within the navigation hierarchy relative to the root.
- Pagination: "Previous" and "Next" buttons at the bottom of pages, derived from the order defined in the
nav.adocfile.
Sources: TECHNICAL_REFERENCE.md:158-175, ui/preview-src/ui-model.yml:45-60
Configuration Options
Navigation behavior can be influenced by attributes set in the antora.yml or the global playbook.
| Attribute | Level | Description |
|---|---|---|
start_page | Component | Defines the landing page when a user enters the component. |
nav | Component | List of AsciiDoc files to use for building the sidebar. |
page-pagination | Page | Boolean attribute to enable/disable previous/next links. |
page-toclevels | Page | Controls the depth of the Table of Contents on a specific page. |
Sources: CONTENT_AUTHORING.md:47-55, TECHNICAL_REFERENCE.md:68-80, ui/preview-src/index.adoc:7-9
Summary
The Navigation System is a robust, file-driven architecture that abstracts complexity away from the content author. By using nav.adoc files and antora.yml configurations, the system ensures that the UI remains consistent while allowing for flexible, multi-versioned documentation across various CircleCI products.
Sources: ARCHITECTURE.md:17-25, TECHNICAL_REFERENCE.md:210-215