This Claude skill provides a robust automation framework for the Docusaurus build and deployment lifecycle. It specializes in aggregating documentation from multiple upstream sources, validating content integrity through MDX linting, and managing the technical infrastructure of a documentation site to ensure seamless, error-free production deployments.

When should I use docs-build?

docs-build is useful in the following scenarios: • Automated Documentation Deployment: Streamlining the build and deployment process for Docusaurus sites to ensure rapid and reliable updates to production environments. • Multi-source Content Aggregation: Automatically fetching and rendering documentation from hundreds of external GitHub repositories to maintain a centralized and synchronized knowledge base. • Quality Assurance & MDX Linting: Detecting syntax errors, unclosed tags, and broken internal links during the build process to prevent deployment failures and improve content reliability. • Redirect & SEO Management: Maintaining site authority and user experience by managing complex redirect rules and sidebar configurations during content migrations or site restructuring.

name	docs-build
description	Building, rendering library docs, and deploying docs.cloudposse.com. Use when working with the Docusaurus build process or regenerating auto-generated content.

Documentation Build System

Instructions for building and maintaining the docs.cloudposse.com site infrastructure.

Local Development

Quick Start

npm install          # Install dependencies (first time or after package.json changes)
npm start            # Start dev server at localhost:3000

Production Build

npm run build        # Build production bundle
npm run serve        # Serve production build locally

Cleaning

npm run clear        # Clear Docusaurus cache
make real-clean      # Full clean (removes node_modules, .docusaurus, build)

Linting

Check MDX syntax before committing:

npx docusaurus-mdx-checker --cwd docs
# or
make lint

Common lint errors:

Unclosed JSX tags
Invalid MDX syntax
Missing imports for components
Broken internal links

Rendering Library Documentation

Warning: These scripts are slow (10+ minutes). They pull from hundreds of upstream repos. Only run when:

Library docs don't exist locally
Explicitly requested to update library content

Library docs are auto-generated in CI/CD for production deployments.

Components (No Token Required)

./scripts/render-docs-for-components.sh

Pulls from cloudposse-terraform-components/ org and renders to docs/components/library/.

Modules (Token Required)

PUBLIC_REPO_ACCESS_TOKEN=<github_token> ./scripts/render-docs-for-modules.sh

Pulls from cloudposse/terraform-aws-* repos and renders to docs/modules/library/.

GitHub Actions (Token Required)

PUBLIC_REPO_ACCESS_TOKEN=<github_token> ./scripts/render-docs-for-github-actions.sh

Pulls from cloudposse/github-action-* repos and renders to docs/github-actions/library/.

Render Script Internals

Scripts are in scripts/docs-collator/:

docs-collator/
├── render_docs_for_components.py
├── render_docs_for_modules.py
├── render_docs_for_github_actions.py
├── AbstractFetcher.py      # Base fetcher class
├── AbstractRenderer.py     # Base renderer class
├── GitHubProvider.py       # GitHub API client
├── ModuleFetcher.py        # Module-specific fetcher
├── ModuleRenderer.py       # Module-specific renderer
├── GitHubActionFetcher.py  # Action-specific fetcher
├── GitHubActionRenderer.py # Action-specific renderer
└── templates/              # Jinja templates for rendered docs

Redirects

Critical: Broken links fail deployment.

Redirect Files

Located in plugins/staticRedirects/redirects/:

File	Purpose
`docs.json`	General documentation moves
`refarch.json`	Reference architecture paths
`deprecated.json`	Deprecated content
`legacy_setup_docs.json`	Legacy setup docs
`components-migration.json`	Component path changes

Adding Redirects

{
  "from": "/old/path/",
  "to": "/new/path/"
}

Add to the appropriate JSON file based on the type of redirect.

Navigation is defined in sidebars.js. Key patterns:

Autogenerated from Directory

{
  type: 'autogenerated',
  dirName: 'layers/identity',
}

Manual Category

{
  type: 'category',
  label: 'Identity',
  link: { type: 'doc', id: 'layers/identity/identity' },
  items: [
    'layers/identity/how-to-log-into-aws',
    // ...
  ]
}

Add to frontmatter:

sidebar_class_name: hidden

Docusaurus Configuration

docusaurus.config.js contains:

Site metadata
Plugin configuration
Theme settings
Algolia search config
Navbar/footer structure
Mermaid diagram settings

Key plugins:

@docusaurus/plugin-client-redirects - Static redirects
docusaurus-plugin-image-zoom - Image lightbox
docusaurus-plugin-llms - LLM-friendly exports
@docusaurus/theme-mermaid - Diagram support

Deployment

Production deployments happen via GitHub Actions. The build:

Runs npm install
Renders library docs (components, modules, actions)
Runs npm run build
Deploys to hosting

Pre-deployment Checklist

npm run build succeeds locally
make lint passes
All redirects added for moved/removed pages
No broken internal links

Troubleshooting

Build Fails with Link Error

Error: Linking for Docs failed for /path/to/doc/

Fix: Add redirect or fix the broken link.

MDX Parse Error

Could not parse MDX file

Fix: Check for unclosed JSX tags, missing imports, or invalid syntax.

Algolia Index Issues

Search is powered by Algolia. Index updates are handled automatically. For search issues, check the Algolia dashboard.

Cache Issues

If seeing stale content:

npm run clear
npm start

docs-build

When & Why to Use This Skill

Use Cases