Update titles and sidebar titles, convert all pages to MDX (#624)

* formatting

* rename for consistency. update titles.

* update titles and sidebar lables. swizzle doccard components

docs/best-practices/best-practices.mdx

@@ -0,0 +1,3 @@
+> <q>Physics is the law, everything else is a recommendation.
+> Anyone can break laws created by people, but I have yet to see anyone break the laws of physics.
+> <p className="author">— **Elon Musk**</p></q>

docs/best-practices/docker-best-practices.md → docs/best-practices/docker.mdx

@@ -1,7 +1,13 @@
 ---
 title: Docker Best Practices
+site_title: Docker
 description: "Collection of some of our docker-specific best practices."
 ---
+import Intro from '@site/src/components/Intro';
+
+<Intro>
+Docker best practices that we follow are listed here. Note that this is not an exhaustive list, but rather some of the ones that have stood out for us as practical ways of leveraging Docker together with the Cloud Posse reference architecture.
+</Intro>
 
 ## Inheritance
 

docs/best-practices/github-feature-branches.md → docs/best-practices/github-feature-branches.mdx

@@ -1,7 +1,12 @@
 ---
 title: Feature Branches
-description: "The Feature Branch Workflow is a requirement for CI/CD. It's a process by which all feature development takes place in a dedicated branch instead of the `master` branch. This makes it easy for multiple developers to collaborate on a particular feature while at the same time ensuring that the master branch remains stable."
+description: "Use separate branches for developing specific features."
 ---
+import Intro from '@site/src/components/Intro'
+
+<Intro>
+The Feature Branch Workflow is a requirement for CI/CD. It's a process by which all feature development takes place in a dedicated branch instead of the `master` branch. This makes it easy for multiple developers to collaborate on a particular feature while at the same time ensuring that the master branch remains stable."
+</Intro>
 
 ## Problem
 

docs/best-practices/make-best-practices.md → docs/best-practices/makefile.mdx

@@ -7,6 +7,11 @@ tags:
   - Makefile
   - best-practices
 ---
+import Intro from '@site/src/components/Intro';
+
+<Intro>
+GNU Makefiles are a convenient way for last-mile automation across multiple tool sets. We used to rely more heavily on Makefiles, but have since transitioned our usage predominantly into Atmos itself. That said, here is a collection of some of the best practices we’ve amassed over the years from extensively leveraging Makefiles.
+</Intro>
 
 ## Avoid using Evals
 

docs/best-practices/markdown-best-practices.md → docs/best-practices/markdown.mdx

@@ -2,6 +2,11 @@
 title: Markdown Best Practices
 description: "Using Markdown is essential for clear communication on mediums such as GitHub, Slack or just plain text. Here are some of our recommendations on when to use certain conventions."
 ---
+import Intro from '@site/src/components/Intro';
+
+<Intro>
+Most of our documentation is provided in Markdown format. Here are some of the conventions and best practices we follow when writing Markdown. Please note that we use the term Markdown loosely to refer to GitHub-flavored Markdown, and we also use quite a bit of MDX, which is what all of our documentation in Docusaurus uses.
+</Intro>
 
 ![Markdown Logo](/assets/13f56b6-markdown.png)
 

docs/community/slack.mdx

@@ -23,5 +23,3 @@ Cloud Posse has a great community of active users who are more than willing to h
         allowtransparency="true"
         style={{ borderRadius: '6px', display: 'flex', marginRight: 'auto', marginLeft: 'auto'}}
         ></iframe>
-
-

docs/community/support.mdx

@@ -1,46 +1,20 @@
 ---
-title: "FAQ"
-confluence: https://cloudposse.atlassian.net/wiki/spaces/REFARCH/pages/1176371788/FAQ
+title: "Community Support"
+sidebar_label: "Support"
 sidebar_position: 100
-custom_edit_url: https://github.com/cloudposse/refarch-scaffold/tree/main/docs/docs/faq.md
 ---
 
 # FAQ
-Here are some quick answers to frequently asked questions. See also our [Troubleshooting](/reference-architecture/reference/troubleshooting) .
+Here are some quick answers to frequently asked questions. See also our [Troubleshooting](/reference-architecture/reference/troubleshooting).
 
 ## Documentation
 
 ### How do I request additional documentation?
 
-Please request documentation via your given team's Slack channel.
+Please request documentation by opening a [GitHub Issue](https://github.com/cloudposse/docs/issues). Please provide as much detail as possible about what you would like to see documented and what related documents you discovered that were not helpful.
 
-### What’s the difference between this documentation and our public documentation?
-
-Our [public documentation](/) is written more generally since we cannot make any assumptions about how the public is using our tools. The reference architecture documentation is more opinionated on how we use our tools, for example, how we layout stacks, components, etc.
-
-## Terraform
-
-### How to upgrade Terraform?
-
-See [How to Switch Versions of Terraform](/reference-architecture/how-to-guides/tutorials/how-to-switch-versions-of-terraform) for a more complete guide.
-
-TL;DR:
-
-- Note the version you want to use
-- Make sure the version is available in [cloudposse/packages](https://github.com/cloudposse/packages/pulls?q=terraform) to see if the version desired is in a merged PR for terraform
-- Make sure the version is available in Spacelift by editing an existing stack and see if the new version is available
-- Update Terraform in `Dockerfile`
-- Update Terraform in `.github/workflows/pre-commit.yaml` github action
-- Update Terraform in `components/terraform/spacelift/default.auto.tfvars`
-
-### How to use `context.tf`?
-
-Copy this file from `https://github.com/cloudposse/terraform-null-label/blob/master/exports/context.tf` and then place it in your Terraform module to automatically get Cloud Posse's standard configuration inputs suitable for passing to Cloud Posse modules.
-
-```
-curl -sL https://raw.githubusercontent.com/cloudposse/terraform-null-label/master/exports/context.tf -o context.tf
-```
-
-Modules should access the whole context as `module.this.context` to get the input variables with nulls for defaults, for example `context = module.this.context`, and access individual variables as `module.this.<var>`, with final values filled in.
+### Can I pay for support?
 
+Yes, we offer paid support via [GitHub Sponsorships](https://github.com/sponsors/cloudposse).
 
+<iframe src="https://github.com/sponsors/cloudposse/card" title="Sponsor Cloud Posse" height="225" width="600" style={{border: 0}}></iframe>

docs/generated/components/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Atmos Components
+sidebar_label: Atmos Components
+description: Atmos Components
+sidebar_position: 0
+---
+
+This is a collection of reusable Atmos Components.
+
+## Introduction
+
+In this library you'll find real-world examples of how we've implemented reusable Atmos Components.

docs/generated/github-actions/index.mdx

@@ -4,9 +4,8 @@ sidebar_label: Overview of GitHub Actions
 description: GitHub Actions
 sidebar_position: 0
 ---
+import Intro from '@site/src/components/Intro'
 
-This is a collection of reusable GitHub Actions.
-
-## Introduction
-
-In this library you'll find real-world examples of how we've implemented reusable GitHub Actions to solve common CI/CD challenges.
+<Intro>
+In this library you'll find all the GitHub Actions we've implemented to solve common CI/CD challenges.
+</Intro>

docs/generated/modules/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Terraform Modules
+sidebar_label: Terraform Modules
+description: Terraform Modules
+sidebar_position: 0
+---
+
+This is a collection of reusable Terraform Modules.
+
+## Introduction
+
+In this library you'll find real-world examples of how we've implemented reusable Terraform Modules.

docs/layers/accounts/accounts.mdx

@@ -1,31 +1,32 @@
 ---
-title: "Accounts"
+title: "Account Management"
+sidebar_label: "Accounts"
 sidebar_class_name: hidden
 ---
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
+import ReactPlayer from "react-player";
 
-# Account Management
-
-This chapter is intended to present how Cloud Posse has designed AWS Account architecture and management. We will
-explain how Cloud Posse provisions and manages AWS Accounts, the reasoning behind our decisions, and how this
-architecture will better align your organization with the
-[AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf)
+<Intro>
+This chapter presents how Cloud Posse designs and manages AWS Account architectures. We will explain how Cloud Posse provisions and manages AWS Accounts, the reasoning behind our decisions, and how this architecture will better align your organization with the [AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf)
+</Intro>
 
-import ReactPlayer from "react-player";
+<KeyPoints>
+- Why to leverage multiple AWS accounts within an AWS Organization
+- How we organize accounts into organizational units (OUs) to manage access and apply Service Control Policies (SCPs) to provide guard rails
+- The set of components we use to provision, configure, and manage AWS accounts, including account-level settings, service control policies, and Terraform state backends, using native Terraform with Atmos
+</KeyPoints>
 
-<ReactPlayer controls url="https://docs.cloudposse.com/assets/refarch/handoffs/account-management.mp4" />
+<figure>
+  <ReactPlayer controls url="https://docs.cloudposse.com/assets/refarch/handoffs/account-management.mp4" />
+  <figcaption>AI generated voice</figcaption>
+</figure>
 
 ## The Problem
 
-The
-[AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf)
-defines AWS architectural best practices and presents a set of foundational questions to enable you to understand how a
-specific architecture aligns with cloud best practices.
+The [AWS Well-Architected Framework](https://docs.aws.amazon.com/pdfs/wellarchitected/latest/userguide/wellarchitected-ug.pdf) defines AWS architectural best practices and presents a set of foundational questions to enable you to understand how a specific architecture aligns with cloud best practices.
 
-The AWS Well-Architected Framework provides several foundational recommendations, one of which is to distribute
-workloads across multiple AWS accounts. However, the framework does not prescribe how this should be achieved. AWS
-offers resources such as Control Tower or Account Factory for provisioning accounts, but these resources have some
-limitations. The primary issue is that they cannot be managed with Terraform, which means that manual effort is required
-to use them.
+The AWS Well-Architected Framework provides several foundational recommendations, one of which is to distribute workloads across multiple AWS accounts. However, the framework does not prescribe how this should be achieved. AWS offers resources such as Control Tower or Account Factory for provisioning accounts, but these resources have some limitations. The primary issue is that they cannot be managed with Terraform, which means that manual effort is required to use them.
 
 ## Our Solution
 

docs/layers/accounts/cloudtrail.mdx

@@ -1,9 +1,10 @@
 ---
-title: "Deploy CloudTrail"
+title: "Deploy CloudTrail and ECR"
+sidebar_label: "Deploy CloudTrail"
 sidebar_position: 30
 ---
-
-# Deploy CloudTrail and ECR
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 Now that all the accounts have been deployed, we need to finalize the setup of the accounts. This includes deploying CloudTrail and ECR. These foundational components will be necessary to move forward with the rest of the deployment.
 

docs/layers/accounts/deploy-accounts.mdx

@@ -1,9 +1,10 @@
 ---
-title: "Deploy Accounts"
+title: "Deploying AWS Accounts"
+sidebar_label: "Deploy Accounts"
 sidebar_position: 20
 ---
-
-# Deploying AWS Accounts
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 | Steps                     |                                                      |
 | ------------------------- | ---------------------------------------------------- |

docs/layers/accounts/design-decisions/decide-on-aws-account-flavors-and-organizational-units.mdx

@@ -1,36 +1,28 @@
 ---
 title: "Decide on AWS Account Flavors and Organizational Units"
+sidebar_label: "AWS Account Flavors and OUs"
+description: "Decide how to organize workloads for isolation and management"
 refarch_id: REFARCH-55
 ---
-
-# Decide on AWS Account Flavors and Organizational Units
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 ## Context and Problem Statement
 
-The
-[AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/userguide/wellarchitected-ug.pdf)
-recommends splitting workloads across multiple AWS accounts.
+The [AWS Well-Architected Framework](https://docs.aws.amazon.com/wellarchitected/latest/userguide/wellarchitected-ug.pdf) recommends splitting workloads across multiple AWS accounts.
 
 When moving to an infrastructure-as-code (IaC) model of infrastructure provisioning, many of the same best practices
 that apply to regular software development should apply to IaC. Part of that is not making changes to a production
-environment that hasn't been tested in a staging environment. If the production and staging environments are in the same
-account, then there are insufficient assurances/guarantees/protections in place to prevent breaking production.
+environment that hasn't been tested in a staging environment. If the production and staging environments are in the same account, then there are insufficient assurances/guarantees/protections in place to prevent breaking production.
 
-Constructs like VPCs only provide network-level isolation, but not IAM-level isolation. And within a single AWS account,
-there’s no practical way to manage IAM-level boundaries between multiple stages like dev/staging/prod. For example, to
-provision most terraform modules, “administrative” level access is required because provisioning any IAM roles requires
-admin privileges. That would mean that a developer needs to be an “admin” in order to iterate on a module.
+Constructs like VPCs only provide network-level isolation, but not IAM-level isolation. And within a single AWS account, there’s no practical way to manage IAM-level boundaries between multiple stages like dev/staging/prod. For example, to provision most terraform modules, “administrative” level access is required because provisioning any IAM roles requires admin privileges. That would mean that a developer needs to be an “admin” in order to iterate on a module.
 
-Leveraging multiple AWS accounts within an AWS Organization is the _only way_ to satisfy these requirements. Guardrails
-can be be in place to restrict what can happen in an account and by whom.
+Leveraging multiple AWS accounts within an AWS Organization is the _only way_ to satisfy these requirements. Guardrails can be be in place to restrict what can happen in an account and by whom.
 
 We must decide how to organize the flat account structure into organizational units. Organizational units can then
 leverage things like Service Control Policies to restrict what can happen inside the accounts.
 
-Multiple AWS accounts should be used to provide a higher degree of isolation by segmenting/isolating workloads. There is
-no additional cost for operating multiple AWS accounts. It does add additional overhead to manage as a standard set of
-components will to manage the account. AWS support only applies to one account, so it may need to be purchased for each
-account unless the organization upgrades to Enterprise Support.
+Multiple AWS accounts should be used to provide a higher degree of isolation by segmenting/isolating workloads. There is no additional cost for operating multiple AWS accounts. It does add additional overhead to manage as a standard set of components will to manage the account. AWS support only applies to one account, so it may need to be purchased for each account unless the organization upgrades to Enterprise Support.
 
 Multiple AWS accounts are all managed underneath an AWS Organization and organized into multiple organizational units
 (OUs). Service Control Policies can restrict what runs in an account and place boundaries around an account that even

docs/layers/accounts/design-decisions/decide-on-aws-organization-strategy.mdx

@@ -1,7 +1,11 @@
 ---
 title: "Decide on AWS Organization Strategy"
+sidebar_label: "AWS Organization Strategy"
+description: Decide whether to create or reuse AWS Organizations
 refarch_id: REFARCH-471
 ---
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 # Decide on AWS Organization Strategy
 

docs/layers/accounts/design-decisions/decide-on-aws-support.mdx

@@ -1,12 +1,16 @@
 ---
 title: "Decide on AWS Support"
+sidebar_label: "AWS Support"
+description: "Decide which accounts need AWS Support"
 refarch_id: REFARCH-417
 ---
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
-# Decide on AWS Support
-
+<Intro>
 AWS Support is always enabled on a per-account basis. With an AWS Enterprise Agreement, AWS support is already included
 from a billing perspective for all accounts, but it still needs to be enabled on a per-account basis.
+</Intro>
 
 :::caution
 

docs/layers/accounts/design-decisions/decide-on-email-address-format-for-aws-accounts.mdx

@@ -1,7 +1,11 @@
 ---
 title: "Decide on Email Address Format for AWS Accounts"
+sidebar_label: "Email Address Format for AWS Accounts"
+description: "Decide what emails will be used for AWS Accounts"
 refarch_id: REFARCH-51
 ---
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 # Decide on Email Address Format for AWS Accounts
 

docs/layers/accounts/design-decisions/decide-on-mfa-solution-for-aws-root-accounts.mdx

@@ -1,9 +1,11 @@
 ---
 title: "Decide on MFA Solution for AWS Root Accounts"
+sidebar_label: "MFA Solution for AWS Root Accounts"
+description: "Decide on MFA Solution for AWS Root Accounts"
 refarch_id: REFARCH-50
 ---
-
-# Decide on MFA Solution for AWS Root Accounts
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 We need an MFA solution for protecting the master AWS accounts. The two most common options are `TOTP` and U2F
 (universal authenticator devices).

docs/layers/accounts/design-decisions/decide-on-terraform-state-backend-architecture.mdx

@@ -1,9 +1,11 @@
 ---
 title: "Decide on Terraform State Backend Architecture"
+sidebar_label: "Terraform State Backend Architecture"
+description: Decide how to organize Terraform State across accounts
 refarch_id: REFARCH-522
 ---
-
-# Decide on Terraform State Backend Architecture
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 ## Context and Problem Statement
 

docs/layers/accounts/initialize-tfstate.mdx

@@ -1,9 +1,10 @@
 ---
-title: "Initialize Terraform Backend"
+title: "Initializing the Terraform State S3 Backend"
+sidebar_label: "Initialize Terraform Backend"
 sidebar_position: 10
 ---
-
-# Initializing the Terraform State S3 Backend
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 | Steps                     |                                           |
 | ------------------------- | ----------------------------------------- |

docs/layers/accounts/prepare-aws-organization.mdx

@@ -1,9 +1,10 @@
 ---
-title: "Prepare your AWS Organization"
+title: "Preparing Your AWS Organization"
+sidebar_label: "Prepare your AWS Organization"
 sidebar_position: 0
 ---
-
-# Preparing Your AWS Organization
+import Intro from '@site/src/components/Intro';
+import KeyPoints from '@site/src/components/KeyPoints';
 
 :::tip Cold Start