Redirect Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Redirect Configuration system within the CircleCI documentation project is a critical infrastructure component designed to manage URL persistence and prevent broken links during site migrations or structural reorganizations. The system primarily leverages AWS S3's built-in website redirect functionality to provide 301 (Permanent) redirects from legacy paths to their new locations within the Antora-generated site structure.
This system ensures that users accessing old URLs are automatically routed to the correct, updated content. It is integrated directly into the production deployment pipeline, allowing for the automated creation of redirect metadata alongside the main site build.
Sources: scripts/README-redirects.md:5-10, ARCHITECTURE.md:25-30
Architecture and Components
The redirect architecture is decoupled from the main content generation but is applied during the deployment phase. It involves mapping legacy documentation paths to the structured output paths generated by Antora.
Core Components
- Mapping Files: YAML or JSON files (such as
redirects_v2.ymlorxref-mapping.json) that define the source and destination paths for documentation assets. - S3 Metadata: The mechanism used to execute redirects. S3 objects are created with
x-amz-website-redirect-locationmetadata. - Deployment Scripts: Shell scripts that automate the creation of redirect objects using the AWS CLI.
The following diagram illustrates the workflow of a user request being redirected by the S3 infrastructure:
This flow shows how S3 intercepts a legacy request and uses object metadata to route the user to the current documentation page.
Sources: scripts/README-redirects.md:12-25, ARCHITECTURE.md:40-45
Implementation via AWS S3
The project utilizes "Redirect Objects" to handle path-based routing. These are empty S3 objects that serve as containers for redirect instructions.
Redirect Metadata Configuration
When a redirect is deployed, an object is created at the legacy path. The aws s3api put-object command is used to set specific flags that tell the S3 website hosting engine to issue a 301 status code.
| Parameter | Value | Description |
|---|---|---|
--key | path/to/old/index.html | The legacy URL location. |
--website-redirect-location | /new/path/index.html | The destination URL. |
--content-length | 0 | Ensures the object carries no data, only metadata. |
Status Code | 301 | Permanent redirect status returned to the browser. |
Sources: scripts/README-redirects.md:38-48
Deployment Process Sequence
The redirection setup is integrated into the deploy-production job. It follows the synchronization of the main site build.
This sequence ensures that redirects are only active once the destination content has been successfully deployed.
Sources: scripts/README-redirects.md:30-36, DEVELOPMENT.md:35-40
URL Mapping and Cross-References
Redirects are often informed by the internal mapping of AsciiDoc files to their final component-based URLs. The project uses a mapping system to track where individual files reside within the Antora component hierarchy.
Component Mapping Examples
Documentation is organized into components like guides, reference, and server-admin. Redirects must point to the specific module and versioned path.
| Legacy ID | Component | Module | Filename |
|---|---|---|---|
executor-intro | guides | execution-managed | executor-intro.adoc |
caching | guides | optimize | caching.adoc |
faq | server-admin-4.6 | operator | faq.adoc |
Sources: archive/scripts/xref-mapping.json:1-150, ARCHITECTURE.md:55-65
API Documentation Redirects
The project maintains specific redirect and routing logic for API documentation (v1 and v2). While the main site uses Antora, API docs are integrated into the /api/ subpath.
- API v1: Static documentation served from
build/api/v1/. - API v2: Generated documentation served from
build/api/v2/.
The build pipeline ensures these paths remain consistent even if the internal source directory structure changes, acting as a functional redirect for API consumers.
Sources: gulp.d/tasks/build-api-docs.js:10-25, antora-playbook.yml:60-70
Validation and Testing
To ensure redirect configurations are accurate, the project includes testing utilities that simulate user requests.
Testing Workflow
- Single Redirect Test:
scripts/test-single-redirect.shvalidates a hardcoded redirect (e.g.,/about-circleci/to/guides/about-circleci/). - Manual Verification: Using
curl -Ito inspect HTTP headers.
# Example validation command
curl -I "https://circleci.com/docs/about-circleci/"
A successful configuration must return HTTP/1.1 301 Moved Permanently with a Location header pointing to the new destination.
Sources: scripts/README-redirects.md:27-35, DEVELOPMENT.md:120-125
Summary
The Redirect Configuration system is a vital part of the documentation lifecycle, providing a bridge between legacy content and the modern Antora-based architecture. By utilizing AWS S3 metadata, the project achieves high-performance redirection without the need for dedicated server-side logic. The integration of mapping files like xref-mapping.json and automated scripts ensures that as the documentation evolves, the user's path to information remains unbroken.