docs-build by cloudposse

---
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

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

### Production Build

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

### Cleaning

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

## Linting

Check MDX syntax before committing:

```bash
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:
1. Library docs don't exist locally
2. Explicitly requested to update library content

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

### Components (No Token Required)

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

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

### Modules (Token Required)

```bash
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)

```bash
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

```json
{
  "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

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

### Manual Category

```javascript
{
  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:

```yaml
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:
1. Runs `npm install`
2. Renders library docs (components, modules, actions)
3. Runs `npm run build`
4. 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:

```bash
npm run clear
npm start
```