// Building, rendering library docs, and deploying docs.cloudposse.com. Use when working with the Docusaurus build process or regenerating auto-generated content.
| 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. |
Instructions for building and maintaining the docs.cloudposse.com site infrastructure.
npm install # Install dependencies (first time or after package.json changes)
npm start # Start dev server at localhost:3000
npm run build # Build production bundle
npm run serve # Serve production build locally
npm run clear # Clear Docusaurus cache
make real-clean # Full clean (removes node_modules, .docusaurus, build)
Check MDX syntax before committing:
npx docusaurus-mdx-checker --cwd docs
# or
make lint
Common lint errors:
Warning: These scripts are slow (10+ minutes). They pull from hundreds of upstream repos. Only run when:
Library docs are auto-generated in CI/CD for production deployments.
./scripts/render-docs-for-components.sh
Pulls from cloudposse-terraform-components/ org and renders to docs/components/library/.
PUBLIC_REPO_ACCESS_TOKEN=<github_token> ./scripts/render-docs-for-modules.sh
Pulls from cloudposse/terraform-aws-* repos and renders to docs/modules/library/.
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/.
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
Critical: Broken links fail deployment.
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 |
{
"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:
{
type: 'autogenerated',
dirName: 'layers/identity',
}
{
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.config.js contains:
Key plugins:
@docusaurus/plugin-client-redirects - Static redirectsdocusaurus-plugin-image-zoom - Image lightboxdocusaurus-plugin-llms - LLM-friendly exports@docusaurus/theme-mermaid - Diagram supportProduction deployments happen via GitHub Actions. The build:
npm installnpm run buildnpm run build succeeds locallymake lint passesError: Linking for Docs failed for /path/to/doc/
Fix: Add redirect or fix the broken link.
Could not parse MDX file
Fix: Check for unclosed JSX tags, missing imports, or invalid syntax.
Search is powered by Algolia. Index updates are handled automatically. For search issues, check the Algolia dashboard.
If seeing stale content:
npm run clear
npm start
Use when creating new Terraform/OpenTofu components or modifying existing ones. Covers required files, catalog defaults, stack configuration, and naming conventions.
Use when authenticating with AWS via Atmos. Covers ATMOS_PROFILE setup, SSO login, and how Atmos automatically assumes the correct identity per stack. Use for authentication setup, SSO login issues, and permission errors.
Use when deploying components via Atmos stacks, configuring stack YAML, or understanding inheritance patterns. Covers catalog defaults, abstract components, stack imports, and how to wire components into target stacks.
Writing standards, React components, and MDX patterns for docs.cloudposse.com. Use when creating or editing documentation content.
CSS styles, color themes, and visual conventions for docs.cloudposse.com. Use when styling components, mermaid diagrams, or working with site theming.
Use when fixing legacy account-map component references or creating new components. Covers migration from dynamic account-map lookups to static account_map variable. Use when you see account-map remote-state references or need to set up provider configuration for a new component.