GitHub Actions Deployment
Relevant source files
The following files were used as context for generating this wiki page:
The GitHub Actions deployment system in this repository serves as an automated synchronization engine that maintains an unofficial mirror of the Claude Code documentation. The primary purpose is to fetch the latest documentation from the canonical source (code.claude.com/docs) and commit updates to the repository every 6 hours. This ensures that downstream tools like ASK and semantic search utilities have access to up-to-date, version-pinned documentation in a machine-readable format.
Sources: README.md:1-5, README.md:11-14
Synchronization Architecture
The deployment logic revolves around the sync.ts script, which treats the official llms.txt file as the source of truth. The system rebuilds the local docs/ directory from scratch on every run, ensuring that page additions, modifications, and deletions are accurately reflected in the Git history.
The Sync Process Flow
The synchronization process follows a strict sequence to prevent data corruption or partial updates. If any network failure occurs during the fetch phase, the process aborts to prevent empty or broken documentation from being committed.
The diagram shows the high-level workflow of the synchronization script executed within the deployment environment.
Sources: sync.ts:1-7, sync.ts:63-65, sync.ts:70-73
Link Rewriting Logic
To ensure that the mirrored documentation remains browsable as local files (e.g., on GitHub's interface), the deployment script performs post-processing on the fetched Markdown content. It converts site-absolute paths (like /en/sub-agents) into relative file paths (like ../sub-agents.md).
| Feature | Description |
|---|---|
| Relative Resolution | Converts /en/slug to ./slug.md or ../slug.md based on directory depth. |
| Anchor Preservation | Maintains URL fragments/anchors while stripping incompatible characters for GitHub. |
| Fallback | If a link points to a page not present in the mirror, it reverts to the canonical absolute URL. |
| JSX Support | Rewrites href attributes in JSX/MDX components alongside standard Markdown links. |
Sources: sync.ts:13-25, sync.ts:31-40
Implementation Details
Core Synchronization Constants
The synchronization script uses specific parameters to balance speed and reliability during deployment.
const BASE = "https://code.claude.com/docs";
const CONCURRENCY = 10;
const RETRIES = 3;
Sources: sync.ts:8-10
Error Handling and Validation
The deployment includes safeguards to prevent "fake deletions" caused by transient network errors or malformed manifests.
- Retry Mechanism: The
fetchTextfunction implements exponential backoff with a 1-second delay multiplied by the attempt number. - Manifest Validation: The script checks if at least 10 pages are found in the manifest before proceeding. If fewer are found, it throws an error and fails the job.
- Atomic-like behavior: The
docs/directory is only deleted after the manifest and the full bundle (llms-full.txt) are successfully retrieved.
Sources: sync.ts:43-57, sync.ts:63-65
Deployment Outcomes
The GitHub Actions deployment produces several artifacts and updates that are utilized by other components of the project:
llms.txt: A manifest of all pages with one-line summaries.llms-full.txt: A single-file bundle containing the entire documentation set.docs/: A structured directory of individual Markdown files.- Git History: A trackable record of documentation changes, allowing users to query when specific pages were added or deleted using commands like
git log --diff-filter=D -- docs/.
Sources: README.md:1-10, README.md:13-16
Conclusion
The GitHub Actions deployment system provides a robust, automated bridge between Anthropic's live documentation and the version-controlled mirror. By combining a strict "source of truth" approach with link rewriting and error-resistant fetching, it ensures that the project remains a reliable foundation for agentic tools and developer reference.