Standardize Command Formatting (#252)

* standardize command formatting

* standardize command formatting

* fix broken link

* fix chapters

* fix slugs and stubs for describing stacks and components

* add id slugs

* fix broken links

* fix links

* Update website/docs/cli/commands/aws/aws-eks-update-kubeconfig.md

Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com>

* Update website/docs/cli/commands/terraform/terraform-shell.md

Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com>

* Update website/docs/core-concepts/stacks/describe-stacks.md

Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com>

* fix typo

* fix links

* fix grammar

Co-authored-by: Andriy Knysh <aknysh@users.noreply.github.com>

website/docs/cli/commands/aws/_category_.json

@@ -5,7 +5,7 @@
   "collapsible": true,
   "collapsed": true,
   "link": {
-    "type": "generated-index",
-    "description": "Atmos AWS Commands"
+    "type": "doc",
+    "id": "usage"
   }
 }

website/docs/cli/commands/aws/aws-eks-update-kubeconfig.md

@@ -3,8 +3,13 @@ title: atmos aws eks update-kubeconfig
 sidebar_label: eks update-kubeconfig
 sidebar_class_name: command
 id: eks-update-kubeconfig
+description: Use this command to download `kubeconfig` from an EKS cluster and saves it to a file.
 ---
 
+:::info Purpose
+Use this command to download `kubeconfig` from an EKS cluster and save it to a file.
+:::
+
 Executes `aws eks update-kubeconfig` command.
 
 ```shell

website/docs/cli/commands/aws/usage.mdx

@@ -0,0 +1,15 @@
+---
+title: atmos aws
+sidebar_label: aws
+sidebar_class_name: command
+description: Atmos AWS Commands
+---
+import DocCardList from '@theme/DocCardList';
+
+:::note Purpose
+Use these subcommands to interact with AWS.
+:::
+
+
+## Subcommands
+<DocCardList />

website/docs/cli/commands/describe/_category_.json

@@ -5,7 +5,7 @@
   "collapsible": true,
   "collapsed": true,
   "link": {
-    "type": "generated-index",
-    "description": "Atmos Describe Commands"
+    "type": "doc",
+    "id": "usage"
   }
 }

website/docs/cli/commands/describe/describe-component.md

@@ -2,10 +2,17 @@
 title: atmos describe component
 sidebar_label: component
 sidebar_class_name: command
-id: describe-component
+id: component
+description: Use this command to describe the complete configuration for a component in a stack.
 ---
 
-Executes `describe component` command.
+:::note Purpose
+Use this command to describe the complete configuration for a component in a stack.
+:::
+
+## Usage
+
+Execute the `describe component` command like this:
 
 ```shell
 atmos describe component <component> -s <stack>

website/docs/cli/commands/describe/describe-config.md

@@ -2,10 +2,17 @@
 title: atmos describe config
 sidebar_label: config
 sidebar_class_name: command
-id: describe-config
+id: config
+description: Use this command to show the final (deep-merged) CLI configuration of all `atmos.yaml` file(s).
 ---
 
-Executes `describe config` command.
+:::note Purpose
+Use this command to show the final (deep-merged) CLI configuration of all `atmos.yaml` file(s).
+:::
+
+## Usage 
+
+Execute the `describe config` command like this:
 
 ```shell
 atmos describe config [options]

website/docs/cli/commands/describe/describe-stacks.md

@@ -2,10 +2,16 @@
 title: atmos describe stacks
 sidebar_label: stacks
 sidebar_class_name: command
-id: describe-stacks
+id: stacks
+description: Use this command to show the fully deep-merged configuration for all stacks and their components in the stacks.
 ---
 
-Executes `describe stacks` command.
+:::note Purpose
+Use this command to show the fully deep-merged configuration for all stacks and their components in the stacks.
+:::
+
+## Usage
+Execute the `describe stacks` command like this:
 
 ```shell
 atmos describe stacks [options]
@@ -35,6 +41,10 @@ atmos describe stacks --components=test/test-component-override-3 --sections=var
 atmos describe stacks --components=test/test-component-override-3 --sections=deps,vars -s=tenant2-ue2-staging
 ```
 
+:::tip
+Use `jq` to filter the output.
+:::
+
 ## Flags
 
 | Flag                | Description                                                                                                                                                                                                                          | Alias | Required |

website/docs/cli/commands/describe/usage.mdx

@@ -0,0 +1,11 @@
+---
+title: atmos describe
+sidebar_label: describe
+sidebar_class_name: command
+description: "Describe Atmos Configurations"
+---
+import DocCardList from '@theme/DocCardList';
+
+## Subcommands
+
+<DocCardList />

website/docs/cli/commands/helmfile/_category_.json

@@ -5,7 +5,7 @@
   "collapsible": true,
   "collapsed": true,
   "link": {
-    "type": "generated-index",
-    "description": "Atmos Helmfile Commands"
+    "type": "doc",
+    "id": "usage"
   }
 }

website/docs/cli/commands/helmfile/helmfile-generate-varfile.md

@@ -3,9 +3,16 @@ title: atmos helmfile generate varfile
 sidebar_label: generate varfile
 sidebar_class_name: command
 id: genereate-varfile
+description: Use this command to generate a varfile for a `helmfile` component in a stack.
 ---
 
-Executes `helmfile generate varfile` command.
+:::note Purpose
+Use this command to generate a varfile for a `helmfile` component in a stack.
+:::
+
+## Usage
+
+Execute the `helmfile generate varfile` command like this:
 
 ```shell
 atmos helmfile generate varfile <component> -s <stack> [options]

website/docs/cli/commands/helmfile/helmfile.md → website/docs/cli/commands/helmfile/usage.mdx

@@ -3,6 +3,15 @@ title: atmos helmfile
 sidebar_label: helmfile
 sidebar_class_name: command
 ---
+import DocCardList from '@theme/DocCardList';
+
+:::note Purpose
+Use these subcommands to run `helmfile` commands.
+:::
+
+# Usage
+
+The `helmfile` integration passes through all arguments to the `helmfile` command. 
 
 Executes `helmfile` commands.
 
@@ -64,3 +73,7 @@ atmos helmfile destroy echo-server --stack=tenant1-ue2-dev
 :::note
 All native `helmfile` flags, command options, and arguments are supported
 :::
+
+## Subcommands
+
+<DocCardList />

website/docs/cli/commands/help.md

@@ -5,6 +5,9 @@ sidebar_class_name: command
 order: 10
 ---
 
+
+## Usage
+
 `atmos help` shows help for all `atmos` CLI commands.
 
 ```shell

website/docs/cli/commands/terraform/_category_.json

@@ -5,7 +5,7 @@
   "collapsible": true,
   "collapsed": false,
   "link": {
-    "type": "generated-index",
-    "description": "Terraform Commands"
+    "type": "doc",
+    "id": "usage"
   }
 }

website/docs/cli/commands/terraform/terraform-clean.md

@@ -5,15 +5,19 @@ sidebar_class_name: command
 id: clean
 ---
 
-Executes `terraform clean` command.
+:::note purpose
+Use this command to delete the `.terraform` folder, the folder that `TF_DATA_DIR` ENV var points to, `.terraform.lock.hcl` file, `varfile` and `planfile` for a
+component in a stack.
+:::
+
+## Usage
+
+Execute the `terraform clean` command like this:
 
 ```shell
 atmos terraform clean <component> -s <stack>
 ```
 
-This command deletes `.terraform` folder, the folder that `TF_DATA_DIR` ENV var points to, `.terraform.lock.hcl` file, `varfile` and `planfile` for a
-component in a stack.
-
 :::tip
 Run `atmos terraform clean --help` to see all the available options
 :::

website/docs/cli/commands/terraform/terraform-generate-backend.md

@@ -3,9 +3,16 @@ title: atmos terraform generate backend
 sidebar_label: generate backend
 sidebar_class_name: command
 id: generate-backend
+description: Use this command to generate a backend config file for an `atmos` terraform component in a stack.
 ---
 
-Executes `terraform generate backend` command.
+:::note purpose
+Use this command to generate a backend config file for an `atmos` terraform component in a stack.
+:::
+
+## Usage
+
+Execute the `terraform generate backend` command like this:
 
 ```shell
 atmos terraform generate backend <command> <component> -s <stack>

website/docs/cli/commands/terraform/terraform-generate-backends.md

@@ -3,9 +3,16 @@ title: atmos terraform generate backends
 sidebar_label: generate backends
 sidebar_class_name: command
 id: generate-backends
+description: Use this command to generate the Terraform "backend config" files for all `atmos` Terraform Components in all Stacks.
 ---
 
-Executes `terraform generate backends` command.
+:::note purpose
+Use this command to generate the Terraform "backend config" files for all `atmos` Terraform [Components](/core-concepts/components) in all [Stacks](/core-concepts/stacks).
+:::
+
+## Usage
+
+Execute the `terraform generate backends` command like this:
 
 ```shell
 atmos terraform generate backends [options]

website/docs/cli/commands/terraform/terraform-generate-varfile.md

@@ -5,7 +5,13 @@ sidebar_class_name: command
 id: generate-varfile
 ---
 
-Executes `terraform generate varfile` command.
+:::note purpose
+Use this command to generate a varfile (`.tfvar` ) for a Terraform [Component](/core-concepts/components) in a [Stack](/core-concepts/stacks).
+:::
+
+## Usage
+
+Execute the `terraform generate varfile` command like this:
 
 ```shell
 atmos terraform generate varfile <command> <component> -s <stack>

website/docs/cli/commands/terraform/terraform-generate-varfiles.md

@@ -3,8 +3,15 @@ title: atmos terraform generate varfiles
 sidebar_label: generate varfiles
 sidebar_class_name: command
 id: generate-varfiles
+description: Use this command to generate the Terraform varfiles (`.tfvar`) for all `atmos` Terraform Components in all Stacks.
 ---
 
+:::note Purpose
+Use this command to generate the Terraform varfiles (`.tfvar`) for all `atmos` Terraform [Components](/core-concepts/components) in all [Stacks](/core-concepts/stacks).
+:::
+
+## Usage
+
 Executes `terraform generate varfiles` command.
 
 ```shell

website/docs/cli/commands/terraform/terraform-shell.md

@@ -3,9 +3,17 @@ title: atmos terraform shell
 sidebar_label: shell
 sidebar_class_name: command
 id: shell
+description: This command starts a new `SHELL` configured with the environment for an `atmos` Component in a Stack so allow executing all native terraform commands inside of the shell without using any atmos-specific arguments and flags.
 ---
 
-Executes `terraform shell` command.
+:::note Purpose
+This command starts a new `SHELL` configured with the environment for an `atmos` Component in a Stack to allow executing all native terraform commands
+inside of the shell without using any atmos-specific arguments and flags.
+:::
+
+## Usage
+
+Execute the `terraform shell` command like this:
 
 ```shell
 atmos terraform shell <component> -s <stack>

website/docs/cli/commands/terraform/terraform-workspace.md

@@ -3,9 +3,16 @@ title: atmos terraform workspace
 sidebar_label: workspace
 sidebar_class_name: command
 id: workspace
+description: This command calculates the `terraform` workspace for an `atmos` component (from the context variables and stack config), then runs `terraform init -reconfigure`, then selects the workspace by executing the `terraform workspace select` command.
 ---
 
-Executes `terraform workspace` command.
+:::note Purpose
+Use this command to calculate the `terraform` workspace for an `atmos` component (from the context variables and stack config), then run `terraform init -reconfigure`, then select the workspace by executing the `terraform workspace select` command.
+:::
+
+## Usage
+
+Execute the `terraform workspace` command like this:
 
 ```shell
 atmos terraform workspace <component> -s <stack>

website/docs/cli/commands/terraform/terraform.md → website/docs/cli/commands/terraform/usage.mdx

@@ -3,6 +3,14 @@ title: atmos terraform
 sidebar_label: terraform
 sidebar_class_name: command
 ---
+import DocCardList from '@theme/DocCardList';
+
+:::note Purpose
+Use these subcommands to interact with `terraform`.
+:::
+
+
+# Usage
 
 Executes `terraform` commands.
 
@@ -93,3 +101,7 @@ atmos terraform clean test/test-component-override-3 -s tenant1-ue2-dev
 :::note
 All native `terraform` flags are supported
 :::
+
+## Subcommands
+
+<DocCardList />

website/docs/cli/commands/validate/_category_.json

@@ -5,7 +5,7 @@
   "collapsible": true,
   "collapsed": true,
   "link": {
-    "type": "generated-index",
-    "description": "Atmos Validate Commands"
+    "type": "doc",
+    "id": "usage"
   }
 }

website/docs/cli/commands/validate/usage.mdx

@@ -0,0 +1,15 @@
+---
+title: atmos validate
+sidebar_label: validate
+sidebar_class_name: command
+description: "Validate Atmos Configurations"
+---
+import DocCardList from '@theme/DocCardList';
+
+:::note Purpose
+Use these subcommands to validate Atmos configurations.
+:::
+
+## Subcommands
+
+<DocCardList />