docs-conventions

name	docs-conventions
description	Writing standards, React components, and MDX patterns for docs.cloudposse.com. Use when creating or editing documentation content.

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.

Good	Bad
Configure Atmos Auth	Atmos Auth
Deploy Roles	IAM Roles
Login to AWS	AWS Login
Setup Identity Center	Identity Center
Understand Identity	Identity Overview

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

Component	Use Case
Card / CardGroup	Grid of linked cards
Note	Inline highlighted notes (use within sections)
Terminal	Terminal output display
File	File content display
CollapsibleText	Expandable sections for long content
AtmosWorkflow	Atmos workflow display
TaskList	Checkbox task lists
KeyPoints	Key takeaways / prerequisites
PillBox	Tag/label pills

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

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

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

Architecture Diagrams

For infrastructure flows, use descriptive node labels:

```mermaid
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"
sidebar_label: "Setup Atmos Pro"
sidebar_position: 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"
sidebar_label: "Deploy Plan Storage"
sidebar_position: 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:
  table_arn: !terraform.state gitops/dynamodb core-use2-auto table_arn
  bucket_arn: !terraform.state gitops/s3-bucket core-use2-auto bucket_arn

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