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.

Sidebar Configuration

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',
    // ...
  ]
}

Hidden from Sidebar

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