Documentation Conventions

Standards and patterns for writing documentation on docs.cloudposse.com.

MDX Frontmatter

Every MDX file requires frontmatter:

---
title: "Human-Readable Title"
sidebar_label: "Action-Oriented Label"
sidebar_class_name: hidden          # Optional: hide from sidebar
description: Brief description for SEO and previews
---

Sidebar Labels

IMPORTANT: Sidebar labels should be action-oriented verbs.

Use verbs like: Configure, Deploy, Setup, Create, Manage, Understand, Review, Migrate

Available React Components

Import components from @site/src/components/:

Steps Component

IMPORTANT: Always wrap lists and numbered items with the <Steps> component.

For compact lists (preferred for simple items):

import Steps from '@site/src/components/Steps';

<Steps>
  1. **First item** — Description of first item
  1. **Second item** — Description of second item
  1. **Third item** — Description of third item
</Steps>

For detailed step-by-step instructions with more content:

import Steps from '@site/src/components/Steps';
import Step from '@site/src/components/Step';
import StepNumber from '@site/src/components/StepNumber';

<Steps>
  <Step>
    ### <StepNumber/> First Step Title
    Step content here with code blocks, notes, etc.
  </Step>
  <Step>
    ### <StepNumber/> Second Step Title
    More content.
  </Step>
</Steps>

Use the compact format for simple lists and the detailed format when steps require code blocks or extensive explanation.

ActionCard with CTAs

For callout boxes with action buttons:

import ActionCard from '@site/src/components/ActionCard';
import PrimaryCTA from '@site/src/components/PrimaryCTA';
import SecondaryCTA from '@site/src/components/SecondaryCTA';

<ActionCard title="What's Next?">
  Description of the next action.
  <div>
    <PrimaryCTA to="/path/to/next/">Primary Action</PrimaryCTA>
    <SecondaryCTA to="/path/to/alt/">Alternative</SecondaryCTA>
  </div>
</ActionCard>

Next Steps Section (Required)

IMPORTANT: All primary pages should end with a "Next Steps" section using ActionCard.

The description should provide context by:

1. Acknowledging what was accomplished in the current page
2. Explaining why the next step is needed
3. Describing what the next page will cover

Pattern: "Now that [what was accomplished], [why the next step matters]. [What the next page covers]."

Good examples:

## Next Steps

<ActionCard title="Centralize root access">
  Now that Identity Center and Permission Sets are provisioned, configure centralized root access management. This allows secure, auditable root operations on member accounts without maintaining root credentials.
  <PrimaryCTA to="/layers/identity/centralized-root-access/">Centralize Root Access</PrimaryCTA>
</ActionCard>

## Next Steps

<ActionCard title="Deploy IAM roles">
  With Permission Sets available for human access, configure IAM roles for machine users. These roles enable GitHub Actions and other CI/CD systems to authenticate via OIDC.
  <PrimaryCTA to="/layers/identity/deploy/">Deploy IAM Roles</PrimaryCTA>
</ActionCard>

## Next Steps

<ActionCard title="Configure authentication">
  With IAM roles deployed for machine users, configure Atmos Auth to map Permission Sets to user profiles. This enables seamless CLI authentication for your team.
  <PrimaryCTA to="/layers/identity/atmos-auth/">Configure Atmos Auth</PrimaryCTA>
</ActionCard>

Bad examples (too generic):

{/* ❌ Too generic - doesn't explain context */}
<ActionCard title="Configure authentication">
  Learn how to configure Atmos Auth.
  <PrimaryCTA to="/layers/identity/atmos-auth/">Configure Atmos Auth</PrimaryCTA>
</ActionCard>

For multiple next steps, use <div> to wrap CTAs:

## Next Steps

<ActionCard title="Setup Identity Center">
  Start by configuring AWS Identity Center with your IdP and deploying Permission Sets for your team.
  <div>
    <PrimaryCTA to="/layers/identity/aws-sso/">Setup Identity Center</PrimaryCTA>
    <SecondaryCTA to="/layers/identity/how-to-log-into-aws/">How to Log into AWS</SecondaryCTA>
  </div>
</ActionCard>

Definition Lists for Component Overviews

Use <dl>/<dt>/<dd> for listing infrastructure components with descriptions:

<dl>
  <dt><code>s3-bucket/gitops</code></dt>
  <dd>
    Stores plan files generated during the planning phase and retrieved during apply.
    Created with the <a href="/components/library/aws/s3-bucket/"><code>s3-bucket</code></a> component.
  </dd>

  <dt><code>dynamodb/gitops</code></dt>
  <dd>
    Maps git SHAs to plan files, ensuring the correct plan is retrieved for each apply.
    Created with the <a href="/components/library/aws/dynamodb/"><code>dynamodb</code></a> component.
  </dd>
</dl>

IMPORTANT: Hyperlinks go on "Created with X component" text in <dd>, NOT on the component name in <dt>.

Note Component vs Admonitions

Use <Note> for inline notes within sections (e.g., inside definition lists):

import Note from '@site/src/components/Note';

<Note>
  These roles are deployed as part of the Identity layer.
</Note>

<Note title="Optional Title">
  Content with a title.
</Note>

Use :::info admonitions for standalone callouts:

:::info Included with Reference Architecture
These workflows are already included with the reference architecture package.
:::

CollapsibleText with CodeBlock

For wrapping long code blocks or workflow tabs:

import CodeBlock from '@theme/CodeBlock';
import CollapsibleText from '@site/src/components/CollapsibleText';
import PartialWorkflow from '@site/examples/snippets/workflows/example.yaml';

<CollapsibleText type="medium">
  <CodeBlock title="example.yaml">{PartialWorkflow}</CodeBlock>
</CollapsibleText>

type="medium" sets the collapsed height. Reference: docs/layers/project/toolbox.mdx:42-48

KeyPoints with TaskList (Prerequisites)

For "Before You Begin" sections, place KeyPoints BEFORE Steps:

import KeyPoints from '@site/src/components/KeyPoints';
import TaskList from '@site/src/components/TaskList';

<KeyPoints title="Before You Begin">
  <TaskList>
    - [x] State Backend configured
    - [x] OIDC Integration deployed
    - [ ] Plan File Storage pending
  </TaskList>
</KeyPoints>

Troubleshooting Sections

Use H3 headers for each issue and TaskList for diagnostic steps:

## Troubleshooting

### No instances appearing

<TaskList>
- Verify the workflow is running successfully
- Check that environment variables are set
- Ensure IAM role has required permissions
</TaskList>

### Remediation failing

<TaskList>
- Verify workflow configuration matches apply workflow
- Check GitHub environments are properly configured
- Review GitHub Actions logs for specific errors
</TaskList>

Workflow Summary Tables

Standard format for listing multiple workflows:

| Workflow | Purpose | Trigger | Frequency |
|----------|---------|---------|-----------|
| `list-instances` | Register components with Atmos Pro | Schedule | Nightly |
| `detect-drift` | Run terraform plan on each instance | Schedule | Weekly |
| `remediate` | Apply fixes for drifted components | Manual | On-demand |

Other Components

Docusaurus Admonitions

Use built-in admonitions for callouts:

:::note
Informational note.
:::

:::tip
Helpful tip.
:::

:::info
General information.
:::

:::warning
Warning about potential issues.
:::

:::danger
Critical warning - data loss, security, etc.
:::

Deprecation Pattern

When deprecating content, add admonition at the top (do NOT move files):

:::warning Deprecated
This documentation describes the legacy approach using `[old thing]`.

**The recommended approach now uses:**
- [New Thing A](/path/to/new-a) for X
- [New Thing B](/path/to/new-b) for Y

This content is preserved for users with existing deployments.
:::

Code Blocks

Basic

atmos terraform apply vpc -s plat-ue1-dev ​```

### With Title

``hcl title="components/terraform/vpc/main.tf" module "vpc" { source = "..." } ​``

### With Line Highlighting

``hcl {2-4} variable "enabled" { type = bool default = true description = "Whether to create resources" } ​``

## Mermaid Diagrams

Mermaid is enabled for diagrams. Use `flowchart LR` for left-to-right diagrams:

flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]
​```

Architecture Diagrams

For infrastructure flows, use descriptive node labels:

flowchart LR subgraph "GitHub Actions" PR["Pull Request"] --> Plan["Terraform Plan"] Plan --> Apply["Terraform Apply"] end

subgraph "Atmos Pro" Plan --> Upload["Upload Plan"] Upload --> Store["S3 Storage"] end

style PR fill:#9b59b6,color:#fff style Plan fill:#3578e5,color:#fff style Apply fill:#28a745,color:#fff ​```

See `docs-styles/SKILL.md` for color conventions.

## Video Embeds

import ReactPlayer from "react-player";

<figure> <ReactPlayer controls url="https://docs.cloudposse.com/assets/..."; /> <figcaption>Video caption</figcaption> </figure>

## Internal Links

Use absolute paths from site root:

[Link Text](/layers/identity/how-to-log-into-aws/)

## TODO Comments for Tracking

Track documentation updates with structured comments:

{/ TODO:PROJECT-NAME - ACTION - Status: Not Started|In Progress|Done /} {/*

Required Updates:

• Update item 1
• Update item 2

*/}

## Writing Style

- **Be concise**: Short sentences, clear language
- **Use active voice**: "Deploy the component" not "The component should be deployed"
- **Lead with the action**: Put commands and code first, explanations after
- **Use consistent terminology**: Follow Cloud Posse naming conventions
- **Avoid jargon**: Define terms on first use or link to glossary

## File Naming

- Use kebab-case: `how-to-deploy-vpc.mdx`
- Layer pages: `{layer-name}.mdx` (e.g., `identity.mdx`)
- Tutorials: `how-to-*.mdx`
- Design decisions: `design-decisions/*.mdx`

## Sidebar Ordering

Control page order within a category using `sidebar_position` in frontmatter:

title: "Setup Atmos Pro" sidebarlabel: "Setup Atmos Pro" sidebarposition: 1

Pages are ordered by `sidebar_position` value (1, 2, 3, etc.). Pages without `sidebar_position` appear after numbered pages in alphabetical order.

**Recommended order pattern:**
1. Main setup/deploy pages
2. Feature configuration pages
3. Tutorials subfolder (autogenerated)

### sidebar_label vs title

Use short `sidebar_label` for navigation, longer `title` for page header:

title: "Deploy Plan File Storage with Atmos and Terraform" sidebarlabel: "Deploy Plan Storage" sidebarposition: 2

## Reference Architecture Naming Conventions

### Tenant Names

| Tenant | Purpose |
|--------|---------|
| `core` | Shared infrastructure (network, automation, identity) |
| `plat` | Platform/application workloads |

### Stage Names

| Stage | Purpose | Example Stack |
|-------|---------|---------------|
| `network` | Network hub account | `core-use1-network` |
| `auto` | Automation/CI account | `core-use1-auto` |
| `dev` | Development environment | `plat-use1-dev` |
| `staging` | Staging environment | `plat-use1-staging` |
| `prod` | Production environment | `plat-use1-prod` |
| `sandbox` | Sandbox/experimentation | `plat-use1-sandbox` |

### Stack Naming Pattern

{tenant}-{region}-{stage}

Examples:
- `core-use1-network` — Network account in us-east-1
- `core-use2-auto` — Automation account in us-east-2
- `plat-use1-dev` — Dev environment in us-east-1
- `plat-use1-prod` — Production in us-east-1

### Component Library URLs

Link to components using path-style URLs:

[vpc](/components/library/aws/vpc/) [tgw/hub](/components/library/aws/tgw/hub/) [iam-role](/components/library/aws/iam-role/)

## YAML Configuration Patterns

### YAML Anchors for DRY Configs

Use anchors to avoid repetition in workflow configurations:

workflows: detect: &detect-config file: atmos-pro-terraform-detect.yaml inputs: upload_status: "true"

remediate: <<: *detect-config file: atmos-pro-terraform-remediate.yaml

### Terraform State References

Use `!terraform.state` for cross-component references:

vars: tablearn: !terraform.state gitops/dynamodb core-use2-auto tablearn bucketarn: !terraform.state gitops/s3-bucket core-use2-auto bucketarn

**Note:** Use `!terraform.state`, NOT `!terraform.output`.