` to wrap CTAs: ```mdx ## Next Steps Start by configuring AWS Identity Center with your IdP and deploying Permission Sets for your team.

Setup Identity Center How to Log into AWS

``` ### Definition Lists for Component Overviews Use `

/

` for listing infrastructure components with descriptions: ```mdx

s3-bucket/gitops: Stores plan files generated during the planning phase and retrieved during apply. Created with the s3-bucket component.
dynamodb/gitops: Maps git SHAs to plan files, ensuring the correct plan is retrieved for each apply. Created with the dynamodb component.

``` **IMPORTANT:** Hyperlinks go on "Created with X component" text in `

`, NOT on the component name in `

`. ### Note Component vs Admonitions Use `` for inline notes within sections (e.g., inside definition lists): ```mdx import Note from '@site/src/components/Note'; These roles are deployed as part of the Identity layer. Content with a title. ``` Use `:::info` admonitions for standalone callouts: ```mdx :::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: ```mdx import CodeBlock from '@theme/CodeBlock'; import CollapsibleText from '@site/src/components/CollapsibleText'; import PartialWorkflow from '@site/examples/snippets/workflows/example.yaml'; {PartialWorkflow} ``` `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: ```mdx import KeyPoints from '@site/src/components/KeyPoints'; import TaskList from '@site/src/components/TaskList'; - [x] State Backend configured - [x] OIDC Integration deployed - [ ] Plan File Storage pending ``` ### Troubleshooting Sections Use H3 headers for each issue and TaskList for diagnostic steps: ```mdx ## Troubleshooting ### No instances appearing - Verify the workflow is running successfully - Check that environment variables are set - Ensure IAM role has required permissions ### Remediation failing - Verify workflow configuration matches apply workflow - Check GitHub environments are properly configured - Review GitHub Actions logs for specific errors ``` ### Workflow Summary Tables Standard format for listing multiple workflows: ```mdx | 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: ```mdx :::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): ```mdx :::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 ```mdx ```bash atmos terraform apply vpc -s plat-ue1-dev ``` ``` ### With Title ```mdx ```hcl title="components/terraform/vpc/main.tf" module "vpc" { source = "..." } ``` ``` ### With Line Highlighting ```mdx ```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: ```mdx ```mermaid flowchart LR A[Start] --> B{Decision} B -->|Yes| C[Action] B -->|No| D[End] ``` ``` ### Architecture Diagrams For infrastructure flows, use descriptive node labels: ```mdx ```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 ```mdx import ReactPlayer from "react-player";

Video caption

``` ## Internal Links Use absolute paths from site root: ```mdx [Link Text](/layers/identity/how-to-log-into-aws/) ``` ## TODO Comments for Tracking Track documentation updates with structured comments: ```mdx {/* 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: ```yaml --- 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: ```yaml --- 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: ```mdx [`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: ```yaml 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: ```yaml 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`.