Refine Metadata and Structure (#632)

* fix broken links

* fix broken links

* fix broken links

* format design decisions, optimize side bar

* fix sidebar positions

* ordering and index pages

* iconify everything

* add more icons, reduce size

* add a few more icons, fix margin

Author: osterman

docs/best-practices/developer/editor-config.mdx

@@ -1,7 +1,7 @@
 ---
 title: Editor Config Best Practices
 sidebar_label: Editor Config
-description: "The EditorConfig enables developers to define and maintain consistent coding styles between different editors and IDEs. It consists of a simple file format (`.editorconfig`) for defining coding styles such as tabs vs spaces. Most text editors support the format and adhere to defined styles. The config files are easily readable and they work nicely with version control systems."
+description: "Enforce consistent formatting using a `.editorconfig`"
 tags:
   - best-practices
   - developer

docs/best-practices/developer/github-sign-your-commits-with-ssh.mdx

@@ -1,6 +1,7 @@
 ---
 title: "Sign Your GitHub Commits with SSH"
 sidebar_label: "Sign GitHub Commits"
+description: Sign all your git commits
 tags:
   - best-practices
   - developer

docs/best-practices/developer/makefile.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Makefile Best Practices"
-description: "We've written thousands of lines of Makefile. These are our best practices from the trenches."
+description: "Best practices for writing Makefiles"
 sidebar_label: Makefiles
 tags:
   - developer

docs/best-practices/developer/markdown.mdx

@@ -1,7 +1,7 @@
 ---
 title: Markdown Best Practices
 sidebar_label: Markdown
-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."
+description: "Use consistent formatting conventions when writing Markdown"
 tags:
   - best-practices
   - developer
@@ -12,8 +12,6 @@ import Intro from '@site/src/components/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)
-
 ## Code Blocks
 
 Use code blocks for anything more than 1 line. Use `code` for inline code, filenames, commands, etc.

docs/best-practices/developer/password-management.mdx

@@ -1,7 +1,8 @@
 ---
 title: Password Management
 sidebar_label: Password Management
-description: ''
+description: Use a password management solution with MFA
+icon: 'material-symbols-light:password'
 tags:
   - best-practices
   - developer

docs/best-practices/developer/semver.mdx

@@ -1,7 +1,7 @@
 ---
 title: Semantic Versioning
 sidebar_label: Semantic Versioning
-description: "Software versioning is the most widely adopted scheme for assigning unique version version numbers to software releases."
+description: "Use semantic versioning the way it was meant to be used"
 tags:
   - semver
   - best-practices

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

@@ -2,6 +2,7 @@
 title: GitHub Feature Branches
 sidebar_label: Feature Branches
 description: "Use separate branches for developing specific features."
+icon: 'carbon:branch'
 tags:
   - best-practices
   - developer

docs/best-practices/github/github-pull-requests.mdx

@@ -2,6 +2,7 @@
 title: GitHub Pull Requests
 sidebar_label: Pull Requests
 description: Best practices using Pull Requests on GitHub.
+icon: 'carbon:pull-request'
 tags:
   - best-practices
   - developer

docs/best-practices/terraform.mdx

@@ -5,11 +5,7 @@ description: "Our opinionated best-practices for Terraform"
 tags:
   - best-practices
   - terraform
-image: /assets/08bcd99-terraform.png
 ---
-
-![Terraform](/assets/08bcd99-terraform.png)
-
 These are the *opinionated* best-practices we follow at Cloud Posse. They are inspired by years of experience writing terraform
 and borrow on the many other helpful resources like those by [HashiCorp](https://www.terraform.io/docs/cloud/guides/recommended-practices/index.html).
 
@@ -314,9 +310,7 @@ configuration to a separate template file.
 
 Linting helps to ensure a consistent code formatting, improves code quality and catches common errors with syntax.
 
-Run `terraform fmt` before committing all code. Use a `pre-commit` hook to
-do this automatically. See [Terraform Tips &
-Tricks](/reference/best-practices/terraform-tips-tricks.md)
+Run `terraform fmt` before committing all code. Use a `pre-commit` hook to do this automatically. See [Terraform Tips & Tricks](/learn/tips-and-tricks/terraform).
 
 Consider using [`tflint`](https://github.com/terraform-linters/tflint) with
 the `aws` plugin.

docs/community/contact-us.mdx

@@ -1,6 +1,6 @@
 ---
 title: Contact Us
-description: 'Cloud Posse is a **DevOps Accelerator**.'
+description: 'Cloud Posse is a **DevOps Accelerator** and here to help you!'
 sidebar_label: Contact Us
 sidebar_position: 200
 ---

docs/community/contribute/contributor-tips.mdx

@@ -7,12 +7,14 @@ tags:
   - contribute
   - developer
 ---
+import Intro from '@site/src/components/Intro';
 import Steps from '@site/src/components/Steps';
+import Note from '@site/src/components/Note';
 
-## About
-
-This document is intended to describe common and not-so-common processes that the contributor team executes as part of maintaining the 300+ open source projects within the Cloud Posse Organization.
 
+<Intro>
+  This document is intended to describe common and not-so-common processes that the contributor team executes as part of maintaining the 300+ open source projects within the Cloud Posse Organization.
+</Intro>
 
 ## Tips & Tricks
 
@@ -60,8 +62,9 @@ Here is a standard usage pattern that contributors can adopt to specific changes
       -- \
       sh -c $PWD/$YOUR_SCRIPT_NAME.sh
       ```
-
-      __NOTE__ the quotes around the message passing this as an argument to `-m` (message)
+      <Note>
+        the quotes around the message passing this as an argument to `-m` (message)
+      </Note>
   1. Verify one of the repos that you're updating exemplifies the changes you're trying to make:
     1. `cd mp/terraform-aws-tfstate-backend/plan/planned/`
     1. `git show`

docs/community/office-hours.mdx

@@ -1,5 +1,5 @@
 ---
-title: Office Hours
+title: Office Hours Registration
 sidebar_position: 3
 sidebar_label: Office Hours
 description: Office Hours with Cloud Posse
@@ -11,8 +11,6 @@ tags:
 import HubspotForm from 'react-hubspot-form'
 import { YouTubePlaylist } from '@codesweetly/react-youtube-playlist';
 
-# Office Hours Registration
-
 <HubspotForm
     portalId='2197148'
     region="na1"

docs/community/support.mdx

@@ -2,20 +2,20 @@
 title: "Community Support"
 sidebar_label: "Support"
 sidebar_position: 100
+description: Get support from our community
 tags:
   - support
   - community
 ---
 
-# FAQ
 Here are some quick answers to frequently asked questions. See also our [Troubleshooting](/resources/legacy/troubleshooting).
 
 ## How can we support you?
 
 By far, the hardest part of being an open-source company is surviving the financial reality that very few companies ever pay for open source. Any financial contribution you can make helps us continue operating as a business, and we've made this easy through GitHub sponsorships.
 
 
-<iframe src="https://github.com/sponsors/cloudposse/card" title="Sponsor Cloud Posse" style={{border: 0}}></iframe>
+<iframe src="https://github.com/sponsors/cloudposse/card" title="Sponsor Cloud Posse" style={{border: 0, width: '100%'}}></iframe>
 
 ## How do I request additional documentation?
 

docs/intro/for-agencies.mdx

@@ -4,7 +4,7 @@ title: Solutions For Agencies & Consultants
 sidebar_label: For Agencies & Consultants
 sidebar_position: 3
 sidebar_class_name: divider
-description: "Standardize your delivery"
+description: "Standardize the delivery to your customers with a framework"
 pagination_prev: intro/enterprises
 tags:
 - agency

docs/intro/for-developers.mdx

@@ -3,6 +3,7 @@ id: developers
 title: "Solutions for Application Developers"
 sidebar_label: "For App Developers"
 sidebar_position: 4
+description: "Focus on app development and ship faster"
 tags:
 - developers
 ---

docs/intro/for-startups.mdx

@@ -2,7 +2,7 @@
 id: startups
 title: Solutions for Startups
 sidebar_label: "For Startups"
-description: "From startup to scale-up with flexible support."
+description: "Deliver your products faster, with support when you need it."
 sidebar_position: 1
 tags: [startups]
 ---

docs/intro/for-terraform-beginners.mdx

@@ -3,6 +3,8 @@ id: terraform-beginner
 title: Solutions for Terraform Beginners
 sidebar_label: "For Terraform Beginners"
 sidebar_position: 5
+description: "Learn by doing and following our best practices"
+icon: "devicon:terraform"
 tags:
 - beginner
 ---

docs/intro/for-terraform-experts.mdx

@@ -3,7 +3,8 @@ id: terraform-expert
 title: Solutions for Experienced Terraformers
 sidebar_label: "For Terraform Experts"
 sidebar_position: 6
-description: Cloud Posse offers flexible, efficient, and lifelong open-source infrastructure.
+description: Don't reinvent the wheel again, leverage a proven framework
+icon: "devicon:terraform"
 tags:
 - expert
 ---

docs/jumpstart/action-items.mdx

@@ -1,7 +1,7 @@
 ---
 title: Action Items
 sidebar_label: Action Items
-sidebar_position: 3
+sidebar_position: 11
 ---
 import Intro from '@site/src/components/Intro';
 import Steps from '@site/src/components/Steps';
@@ -88,14 +88,14 @@ Before we can get started, here's the minimum information we need from you.
 
 ## GitHub Self-Hosted Runners
 
-### Self Hosted Github Runners on EKS
+### Self-Hosted Github Runners on EKS
 
 If you are deploying the Actions Runner Controller solution for Self-Hosted Github Runners, please generate the required secrets following the
-[GitHub Action Runner Controller setup docs](/reference-architecture/setup/github-arc/#requirements).
+[GitHub Action Runner Controller setup docs](/layers/github-actions/eks-github-actions-controller#requirements).
 
 Feel free to store these secrets in 1Password if you do not have AWS access yet. Cloud Posse can complete the setup from there.
 
-### Self Hosted Github Runners with Philips Labs (ECS)
+### Self-Hosted Github Runners with Philips Labs (ECS)
 
 If you have chosen ECS as a platform, we recommend deploying Philips Labs GitHub Action Runners. Please read through the [Philips Labs GitHub Action Runners Setup Requirements](/layers/github-actions/philips-labs-github-runners#requirements).
 

docs/jumpstart/faq.mdx

@@ -1,7 +1,7 @@
 ---
 title: FAQ
 sidebar_label: FAQ
-sidebar_position: 10
+sidebar_position: 15
 description: Frequently Asked Questions
 tags:
   - faq
@@ -14,7 +14,7 @@ These are some of the most frequently asked questions by customers during our Ki
 
 ### What is the difference between a Service Discovery Domain and a Vanity Domain?
 
-This is an extremely common question. Please see [What is the difference between a Vanity and a Service Domain?](/reference-architecture/fundamentals/network-and-dns/#what-is-the-difference-between-a-vanity-and-a-service-domain)
+This is an extremely common question. Please see [What is the difference between a Vanity and a Service Domain?](/layers/network#what-is-the-difference-between-a-vanity-and-a-service-domain)
 
 ### Do we have to use 1Password?
 

docs/jumpstart/kick-off.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Kick Off with Cloud Posse"
 sidebar_label: "Kick Off"
-sidebar_position: 2
+sidebar_position: 10
 describe: Set project expectations for Jumpstarts with Cloud Posse
 ---
 import Link from '@docusaurus/Link'
@@ -47,14 +47,14 @@ This document outlines what to expect from your first call with Cloud Posse. In
   <Step>
     ### <StepNumber/> Project Overview
 
-    Cloud Posse will begin deploying your infrastructure following the [Reference Architecture](/reference-architecture/) and your team's design decisions. The Reference Architecture is a collection of best practices for building a secure, scalable, and highly available infrastructure on AWS. The Reference Architecture is a living document that is constantly evolving as we learn from our customers and the community.
+    Cloud Posse will begin deploying your infrastructure [starting with the foundation](/layers/foundation) based your team's design decisions. The Reference Architecture is a collection of best practices for building a secure, scalable, and highly available infrastructure on AWS. The Reference Architecture is a living document that is constantly evolving as we learn from our customers and the community.
 
-    We will deploy your infrastructure in _layers_. These layers are designed to manage collections of deliverables and will be a mix of generated content from a private reference, vendored Terraform from open source libraries, and any customization for your Organization. Because we are delivering an entire infrastructure repository, these initial PRs will be massive; a complete infrastructure set up requires dozens of components, each with Terraform modules, configuration, account setup, and documentation. You are absolutely welcome to follow along, but we do not intend for your team to be required to review these massive PRs. Cloud Posse internally reviews these PRs extensively to ensure that the final product works as intended.
+    We will deploy your infrastructure in _layers_. These layers are designed to manage collections of deliverables and will be a mix of generated content from a private reference, vendored Terraform from open-source libraries, and any customization for your Organization. Because we are delivering an entire infrastructure repository, these initial PRs will be massive; a complete infrastructure setup requires dozens of components, each with Terraform modules, configuration, account setup, and documentation. You are absolutely welcome to follow along, but we do not intend for your team to be required to review these massive PRs. Cloud Posse internally reviews these PRs extensively to ensure that the final product works as intended.
 
-    Once we're confident that we've deployed a given layer entirely, we then schedule the [Hand-Off Calls](#handoff-calls). A handoff call is intended to explain a given topic and provide the opportunity for your team to review and provide feedback on any given layer, as well as answer other questions. Before each Hand-Off Call we will have a [Fundamental Six Pager](/reference-architecture/category/fundamentals/) that goes into detail on the subject, but we can use the handoff calls however best suites your team. These calls can be a lecture of the material from the given six pager, a demo from Cloud Posse, or an opportunity practice hands-on labs.
+    Once we're confident that we've deployed a given layer entirely, we then schedule the [Hand-Off Calls](#handoff-calls). A handoff call is intended to explain a given topic and provide the opportunity for your team to review and provide feedback on any given layer, as well as answer other questions. Before each Hand-Off Call, review the fundamentals of every layer by watching the videos. While we can use the handoff calls, teams can feel overwhelmed if they haven't watched any of the handoff videos beforehand. These calls can be a lecture on the material for any given layer, a demo from Cloud Posse, or an opportunity to practice with hands-on labs.
 
     <Admonition type="tip">
-      If you come prepared to a Hand-Off call, we can skip the lecture and spend more time answering questions or working through hands-on labs.
+      If you come prepared for Hand-Off calls, we can skip the lecture and spend more time answering questions or working through hands-on labs.
     </Admonition>
   </Step>
 
@@ -95,7 +95,7 @@ This document outlines what to expect from your first call with Cloud Posse. In
   </Step>
 
   <Step>
-    ### <StepNumber/> Review [Design Decisions](/reference-architecture/fundamentals/design-decisions)
+    ### <StepNumber/> Review Design Decisions
 
     <TaskList>
       - [ ] [Decide on Namespace Abbreviation](/layers/foundation/design-decisions/decide-on-namespace-abbreviation)
@@ -106,7 +106,7 @@ This document outlines what to expect from your first call with Cloud Posse. In
       - [ ] [Decide on Primary AWS Region and Secondary AWS Region](/layers/network/design-decisions/decide-on-primary-aws-region)
       - [ ] [Decide on CIDR Allocation Strategy](/layers/network/design-decisions/decide-on-cidr-allocation)
       - [ ] [Decide on Service Discovery Domain](/layers/network/design-decisions/decide-on-service-discovery-domain)
-      - [ ] [Decide on Vanity Domain](/reference-architecture/reference/adrs/jumpstart/decide-on-vanity-domain/)
+      - [ ] [Decide on Vanity Domain](/layers/network/design-decisions/decide-on-vanity-branded-domain)
       - [ ] [Decide on Release Engineering Strategy](/layers/software-delivery/design-decisions/decide-on-release-engineering-strategy)
     </TaskList>
   </Step>
@@ -117,11 +117,11 @@ This document outlines what to expect from your first call with Cloud Posse. In
     Generally, expect to schedule the following Handoff calls. These are subject to change and should be adaptable to fit your individual engagement.
     <TaskList>
       - [Kick Off](/jumpstart/kick-off)
-      - [Introduction to Toolset](/reference-architecture/fundamentals)
-      - [Identity and Authentication](/reference-architecture/fundamentals/iam-identity/)
+      - [Introduction to Toolset](/layers/foundation)
+      - [Identity and Authentication](/layers/identity)
       - [Component Development](/learn/component-development)
-      - [Account Management](/reference-architecture/fundamentals/account-management/)
-      - [Network and DNS](/reference-architecture/fundamentals/network-and-dns/)
+      - [Account Management](/layers/accounts/)
+      - [Network and DNS](/layers/network/)
       - [Spacelift](/layers/spacelift) or [GitOps](/layers/gitops)
       - [ECS](/layers/ecs) or [EKS](/layers/eks)
       - [Monitoring](/layers/monitoring) and [Alerting](/layers/alerting)

docs/jumpstart/onboarding.mdx

@@ -1,7 +1,7 @@
 ---
 title: Onboarding
 sidebar_label: Onboarding
-sidebar_position: 4
+sidebar_position: 13
 ---
 import TaskList from '@site/src/components/TaskList';