Markdown numbering consistency and updated contribution guide (#983)

* explanation of numbered lists for markdown in contribution guide

* numbered lists changed to 1 for all markdown

Signed-off-by: Emanuel Palm <[email protected]>

---------

Signed-off-by: Emanuel Palm <[email protected]>
Signed-off-by: Aaron Crawfis <[email protected]>
Co-authored-by: Aaron Crawfis <[email protected]>

docs/README.md

@@ -7,10 +7,10 @@ This directory contains the files to generate the https://docs.radapp.io site. P
 The easiest way to get up and runnning with a docs environment is a GitHub codespace.
 
 1. Open codespace
-2. Ensure postCreate script has completed (takes ~2 minutes)
-3. Run `cd docs` to change into the docs directory
-4. Run `npm run start` to run a docs server
-5. Click the `localhost:1313` link in your terminal to open the Codespace tunnel to the page
+1. Ensure postCreate script has completed (takes ~2 minutes)
+1. Run `cd docs` to change into the docs directory
+1. Run `npm run start` to run a docs server
+1. Click the `localhost:1313` link in your terminal to open the Codespace tunnel to the page
 
 ## Local machine
 

docs/content/community/contributing/contributing-docs/index.md

@@ -26,10 +26,10 @@ It's easy to get up and running with a GitHub Codespace. This will give you a fu
 > Note the `postCreateCommand` may take up to 3 minutes to complete after the codespace is created to complete.
 
 1. Start Codespace
-2. Wait for `postCreateCommand` to complete
-3. Run `cd docs` to enter the hugo site directory
-4. Run `hugo server` to start the local server
-5. Click on the link in the terminal to open the docs in your browser
+1. Wait for `postCreateCommand` to complete
+1. Run `cd docs` to enter the hugo site directory
+1. Run `hugo server` to start the local server
+1. Click on the link in the terminal to open the docs in your browser
 
 ### Local machine
 
@@ -42,35 +42,35 @@ It's easy to get up and running with a GitHub Codespace. This will give you a fu
 ### Environment setup
 
 1. Ensure pre-requisites are installed
-2. Clone this repository and the radius repository
+1. Clone this repository and the radius repository
 
    ```sh
    git clone https://github.com/radius-project/radius.git
    git clone https://github.com/radius-project/docs.git
    ```
 
-3. Generate CLI docs:
+1. Generate CLI docs:
 
    ```sh
    pushd radius
    go run ./cmd/docgen/main.go ../docs/docs/content/reference/cli
    popd
    ```
 
-4. Update submodules:
+1. Update submodules:
 
    ```sh
    cd docs
    git submodule update --init --recursive
    ```
 
-5. Install npm packages:
+1. Install npm packages:
 
    ```sh
    npm install
    ```
 
-6. Initialize the docsy theme:
+1. Initialize the docsy theme:
 
    ```sh
    cd themes/docsy
@@ -81,13 +81,13 @@ It's easy to get up and running with a GitHub Codespace. This will give you a fu
 ### Run local server
 
 1. Make sure you're still in the `docs` directory
-2. Run
+1. Run
 
    ```sh
    hugo server
    ```
 
-3. Navigate to `http://localhost:1313/`
+1. Navigate to `http://localhost:1313/`
 
 ## Developer Certificate of Origin
 
@@ -114,9 +114,9 @@ Visual Studio Code has a setting, `git.alwaysSignOff` to automatically add a Sig
 There are 5 types of docs in Radius:
 
 1. **Concept** - A concept doc is a high-level overview of the project or an area of the project.
-2. **Overview** - A overview page documents a specific feature or capability of the project, with information on what the feature is and additional context and links on how to use it.
-3. **How-To** - A how-to guide is a step-by-step guide to help the reader achieve a specific task. It assumes the reader has a basic understanding of the project and its concepts. For more information on how-to guides, see [Diátaxis](https://diataxis.fr/how-to-guides/).
-4. **Reference** - A reference doc is a detailed description of a specific feature or capability of the project. It assumes the reader has a basic understanding of the project and its concepts. For more information on reference docs, see [Diátaxis](https://diataxis.fr/reference/).
+1. **Overview** - A overview page documents a specific feature or capability of the project, with information on what the feature is and additional context and links on how to use it.
+1. **How-To** - A how-to guide is a step-by-step guide to help the reader achieve a specific task. It assumes the reader has a basic understanding of the project and its concepts. For more information on how-to guides, see [Diátaxis](https://diataxis.fr/how-to-guides/).
+1. **Reference** - A reference doc is a detailed description of a specific feature or capability of the project. It assumes the reader has a basic understanding of the project and its concepts. For more information on reference docs, see [Diátaxis](https://diataxis.fr/reference/).
 
 Overall:
 
@@ -177,6 +177,18 @@ These conventions should be followed throughout all Radius documentation to ensu
 
 The docs pipeline uses [aspell](http://aspell.net/) to check for spelling mistakes. If you need to add a new custom word to the allow-list, update `.github/config/en-custom.txt`.
 
+### Numbering
+
+All numbered lists use `1.` as the number, regardless of the order. The list numbers are then incremented automatically during the build process of the docs.
+
+#### Example
+
+```md
+1. This is the second step, and will be displayed with a 2 in the docs.
+1. This is the third step, and will be displayed with a 3.
+1. This is the first step of a process.
+```
+
 ## Tips and tricks
 
 Any contribution must ensure not to break the website build. The way Hugo builds the website requires following the below guidance.

docs/content/concepts/architecture-concept/index.md

@@ -130,9 +130,9 @@ This section describes example tasks that can be performed with Radius and how t
 When listing applications using the `rad` CLI:
 
 1. The client sends an HTTP request to the Radius API requesting the list of applications.
-2. UCP receives the request for the `Applications.Core/applications` List operation and looks up the internal address for the `Applications.Core` resource provider.
-3. UCP proxies the HTTP request to the `Applications.Core` resource provider.
-4. The `Applications.Core` resource provider handles the request and responds with the list of applications.
+1. UCP receives the request for the `Applications.Core/applications` List operation and looks up the internal address for the `Applications.Core` resource provider.
+1. UCP proxies the HTTP request to the `Applications.Core` resource provider.
+1. The `Applications.Core` resource provider handles the request and responds with the list of applications.
 
 {{< image src="flow-list-apps.png" alt="Diagram of the API flow described above" width="1000px" >}}
 
@@ -142,9 +142,9 @@ When listing applications using the `rad` CLI:
 When using Bicep to author and deploy Radius Applications:
 
 1. The client compiles the Bicep file to an ARM-JSON template and submits a request for processing as a `Bicep.Deployments/deployments` resource.
-2. UCP receives the request for the `Bicep.Deployments/deployments` Create operation and looks up the internal address for the `Bicep.Deployments` resource provider.
-3. UCP proxies the HTTP request to the `Bicep.Deployments` resource provider.
-4. The `Bicep.Deployments` resource provider processes the ARM-JSON template. For each resource in the template:
+1. UCP receives the request for the `Bicep.Deployments/deployments` Create operation and looks up the internal address for the `Bicep.Deployments` resource provider.
+1. UCP proxies the HTTP request to the `Bicep.Deployments` resource provider.
+1. The `Bicep.Deployments` resource provider processes the ARM-JSON template. For each resource in the template:
   a. The `Bicep.Deployments` resource provider makes a request to UCP to Create/Update the resource.
   b. UCP routes the request to the appropriate resource provider to be handled.
 

docs/content/concepts/faq/index.md

@@ -84,7 +84,7 @@ Yes. Radius has first-class support for [Dapr building blocks]({{< ref "/guides/
 Radius leverages Kubernetes in two ways:
 
 1. As a hosting platform for the Radius control-plane
-2. As a runtime for containerized workloads
+1. As a runtime for containerized workloads
 
 While Radius only supports Kubernetes today, it is architected to support other hosting platforms in the future, including serverless platforms. Radius is not a Kubernetes controller and the primary user experience is not through CRDs. Instead, Radius Applications are an abstraction layer on top of Kubernetes and other cloud platforms.
 

docs/content/guides/author-apps/aws/howto-aws-resources/index.md

@@ -99,15 +99,15 @@ This creates a container that will be deployed to your Kubernetes cluster. This
 
 1. When you're done with testing, you can use the rad CLI to [delete an environment]({{< ref rad_env_delete.md >}}) to delete all Radius resources running on the EKS Cluster.
 
-2. Cleanup AWS Resources - AWS resources are not deleted when deleting a Radius Environment, so make sure to delete all resources created in this reference app to prevent additional charges. You can delete these resources in the AWS Console or via the AWS CLI. Instructions to delete an AWS S3 Bucket are available [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html).
+1. Cleanup AWS Resources - AWS resources are not deleted when deleting a Radius Environment, so make sure to delete all resources created in this reference app to prevent additional charges. You can delete these resources in the AWS Console or via the AWS CLI. Instructions to delete an AWS S3 Bucket are available [here](https://docs.aws.amazon.com/AmazonS3/latest/userguide/delete-bucket.html).
 
 ## Troubleshooting
 
 If you hit errors while deploying the application, please follow the steps below to troubleshoot:
 
 1. Check if the AWS credentials are valid. Login to the AWS console and check if the IAM access key and secret access key are valid and not expired.
 
-2. Look at the control plane logs to see if there are any errors. You can use the following command to view the logs:
+1. Look at the control plane logs to see if there are any errors. You can use the following command to view the logs:
 
      ```bash
      rad debug-logs

docs/content/guides/author-apps/azure/howto-azure-resources/index.md

@@ -60,7 +60,7 @@ rad deploy ./app.bicep -p oidcIssuer=<OIDC_ISSUER_URL>
    rad resource logs containers mycontainer -a myapp
    ```
 
-2. You should see the contents of the secret from your Key Vault:
+1. You should see the contents of the secret from your Key Vault:
 
    ```txt
    [myapp-mycontainer-79c54bd7c7-tgdpn] I1108 18:39:53.636314       1 main.go:33] "successfully got secret" secret="supersecret"
@@ -76,4 +76,4 @@ rad deploy ./app.bicep -p oidcIssuer=<OIDC_ISSUER_URL>
    rad app delete myapp --yes
    ```
 
-2. Delete the deployed Azure Key Vault via the Azure portal or the Azure CLI
+1. Delete the deployed Azure Key Vault via the Azure portal or the Azure CLI

docs/content/guides/author-apps/containers/howto-keyvault-volume/index.md

@@ -67,7 +67,7 @@ rad deploy ./app.bicep -p oidcIssuer=<OIDC_ISSUER_URL>
    rad resource logs containers mycontainer -a myapp
    ```
 
-2. You should see the contents of the `/var/secrets` mount path defined in your `app.bicep` file:
+1. You should see the contents of the `/var/secrets` mount path defined in your `app.bicep` file:
 
    ```
    [myapp-mycontainer-d8b4fc44-qrhnn] secret context : supersecret
@@ -82,5 +82,5 @@ rad deploy ./app.bicep -p oidcIssuer=<OIDC_ISSUER_URL>
    ```bash
    rad app delete myapp --yes
    ```
-
-2. Delete the deployed Azure Key Vault via the Azure portal or the Azure CLI
+   
+1. Delete the deployed Azure Key Vault via the Azure portal or the Azure CLI

docs/content/guides/author-apps/kubernetes/how-to-patch-pod/index.md

@@ -56,7 +56,7 @@ Begin by creating a file named `app.bicep` with a Radius [container]({{< ref "gu
 
    <br> When you're ready to move on to the next step, use `CTRL` + `C` to exit the command.
 
-2. Run the command below, which will list the pods in your Kubernetes cluster, using the `-o` flag to specify the relevant information to output:
+1. Run the command below, which will list the pods in your Kubernetes cluster, using the `-o` flag to specify the relevant information to output:
 
    ```bash
    kubectl get pods -A -l app.kubernetes.io/name=demo -o custom-columns=POD:.metadata.name,STATUS:.status.phase,CONTAINER_NAMES:spec.containers[:].name,CONTAINER_IMAGES:spec.containers[:].image
@@ -105,7 +105,7 @@ Add the following [`runtimes`]({{< ref "reference/resource-schema/core-schema/co
 
    <br> When you're ready to move on to the next step, use `CTRL` + `C` to exit the command.
 
-2. Run the command below, which will list the pods in your Kubernetes cluster, using the `-o` flag to specify the relevant information to output:
+1. Run the command below, which will list the pods in your Kubernetes cluster, using the `-o` flag to specify the relevant information to output:
 
    ```bash
    kubectl get pods -A -l app.kubernetes.io/name=demo -o custom-columns=POD:.metadata.name,STATUS:.status.phase,CONTAINER_NAMES:spec.containers[:].name,CONTAINER_IMAGES:spec.containers[:].image

docs/content/guides/deploy-apps/environments/howto-environment/index.md

@@ -40,7 +40,7 @@ Radius Environments can be setup with the rad CLI via two paths: interactive or
    ⏳ Update local configuration
    ```
 
-2. Verify the initialization by running:
+1. Verify the initialization by running:
    ```bash
    kubectl get deployments -n radius-system
    ```
@@ -60,9 +60,7 @@ Radius Environments can be setup with the rad CLI via two paths: interactive or
    ```bash
    rad env list
    ```
-
-3. Use `rad recipe list` to see the list of available Recipes:
-
+1. Use `rad recipe list` to see the list of available Recipes:
    ```bash
    rad recipe list
    ```

docs/content/guides/deploy-apps/howto-delete/index.md

@@ -23,7 +23,7 @@ rad app delete <appname>
 This will delete the following resources from the Radius Environment
 
 1. All the resources created by Radius on the Kubernetes cluster under the `<namespace-name>-<app-name>` namespace
-2. All the resources provisioned by Recipes
+1. All the resources provisioned by Recipes
 
 ## Step 2: Delete any cloud/platform resources
 

docs/content/guides/operations/control-plane/logs/fluentd/index.md

@@ -22,14 +22,14 @@ tags: ["logs","observability"]
     kubectl create namespace radius-monitoring
     ```
 
-2. Add the helm repo for Elastic Search
+1. Add the helm repo for Elastic Search
 
     ```bash
     helm repo add elastic https://helm.elastic.co
     helm repo update
     ```
 
-3. Install Elastic Search using Helm
+1. Install Elastic Search using Helm
 
     _By default, the chart creates three replicas which must be on different nodes. If your cluster has fewer than 3 nodes, specify a smaller number of replicas with the `--set replicas=1` flag:_
 
@@ -43,13 +43,13 @@ tags: ["logs","observability"]
     helm install elasticsearch elastic/elasticsearch --version 7.17.3 -n radius-monitoring --set persistence.enabled=false,replicas=1
     ```
 
-4. Install Kibana
+1. Install Kibana
 
     ```bash
     helm install kibana elastic/kibana --version 7.17.3 -n radius-monitoring
     ```
 
-5. Ensure that Elastic Search and Kibana are running in your Kubernetes cluster
+1. Ensure that Elastic Search and Kibana are running in your Kubernetes cluster
 
     ```bash
     kubectl get pods -n radius-monitoring
@@ -80,7 +80,7 @@ tags: ["logs","observability"]
     kubectl apply -f ./fluentd-radius-with-rbac.yaml
     ```
 
-2. Ensure that Fluentd is running as a daemonset. The number of Fluentd instances should be the same as the number of cluster nodes. In the example below, there is only one node in the cluster:
+1. Ensure that Fluentd is running as a daemonset. The number of Fluentd instances should be the same as the number of cluster nodes. In the example below, there is only one node in the cluster:
 
     ```bash
     kubectl get pods -n kube-system -w
@@ -129,37 +129,37 @@ _Note: There is a small delay for Elastic Search to index the logs that Fluentd
 
 1. Browse to `http://localhost:5601`
 
-2. Expand the drop-down menu and click **Management → Stack Management**
+1. Expand the drop-down menu and click **Management → Stack Management**
 
     ![Stack Management item under Kibana Management menu options](kibana-1.png)
 
-3. On the Stack Management page, select **Data → Index Management** and wait until `radius-*` is indexed.
+1. On the Stack Management page, select **Data → Index Management** and wait until `radius-*` is indexed.
 
     ![Index Management view on Kibana Stack Management page](kibana-2.png)
 
-4. Once `radius-*` is indexed, click on **Kibana → Index Patterns** and then the **Create index pattern** button.
+1. Once `radius-*` is indexed, click on **Kibana → Index Patterns** and then the **Create index pattern** button.
 
     ![Kibana create index pattern button](kibana-3.png)
 
-5. Define a new index pattern by typing `radius*` into the **Index Pattern name** field, then click the **Next step** button to continue.
+1. Define a new index pattern by typing `radius*` into the **Index Pattern name** field, then click the **Next step** button to continue.
 
     ![Kibana define an index pattern page](kibana-4.png)
 
-6. Configure the primary time field to use with the new index pattern by selecting the `@timestamp` option from the **Time field** drop-down. Click the **Create index pattern** button to complete creation of the index pattern.
+1. Configure the primary time field to use with the new index pattern by selecting the `@timestamp` option from the **Time field** drop-down. Click the **Create index pattern** button to complete creation of the index pattern.
 
     ![Kibana configure settings page for creating an index pattern](kibana-5.png)
 
-7. The newly created index pattern should be shown. Confirm that the fields of interest such as `scope`, `type`, `app_id`, `level`, etc. are being indexed by using the search box in the **Fields** tab.
+1. The newly created index pattern should be shown. Confirm that the fields of interest such as `scope`, `type`, `app_id`, `level`, etc. are being indexed by using the search box in the **Fields** tab.
 
     _Note: If you cannot find the indexed field, please wait. The time it takes to search across all indexed fields depends on the volume of data and size of the resource that the elastic search is running on._
 
     ![View of created Kibana index pattern](kibana-6.png)
 
-8. To explore the indexed data, expand the drop-down menu and click **Analytics → Discover**.
+1. To explore the indexed data, expand the drop-down menu and click **Analytics → Discover**.
 
     ![Discover item under Kibana Analytics menu options](kibana-7.png)
 
-9. In the search box, type in a query string such as `scope:*` and click the **Refresh** button to view the results.
+1. In the search box, type in a query string such as `scope:*` and click the **Refresh** button to view the results.
 
     _Note: This can take a long time. The time it takes to return all results depends on the volume of data and size of the resource that the elastic search is running on._
 

docs/content/guides/operations/control-plane/metrics/prometheus/index.md

@@ -25,7 +25,7 @@ tags: ["metrics", "observability"]
    kubectl create namespace radius-monitoring
    ```
 
-2. Install Prometheus into your monitoring namespace:
+1. Install Prometheus into your monitoring namespace:
 
    ```bash
    helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
@@ -39,7 +39,7 @@ tags: ["metrics", "observability"]
    helm install radius-prom prometheus-community/prometheus -n radius-monitoring --set alertmanager.persistentVolume.enable=false --set pushgateway.persistentVolume.enabled=false --set server.persistentVolume.enabled=false
    ```
 
-3. Validate your Prometheus installation:
+1. Validate your Prometheus installation:
 
    ```bash
    kubectl get pods -n radius-monitoring

docs/content/guides/operations/control-plane/traces/jaeger/index.md

@@ -24,17 +24,17 @@ The following steps show you how to configure the Radius control plane to send d
    kubectl create namespace radius-monitoring
    ```
 
-2. Create the file `jaeger.yaml`, and paste the following YAML:
+1. Create the file `jaeger.yaml`, and paste the following YAML:
 
    {{< button text="Download jaeger.yaml" link="jaeger.yaml" >}}
 
-3. Install Jaeger:
+1. Install Jaeger:
 
    ```bash
    kubectl apply -f jaeger.yaml
    ```
 
-4. Wait for Jaeger to be up and running
+1. Wait for Jaeger to be up and running
 
    ```bash
    kubectl wait deploy --selector app=jaeger --for=condition=available -n radius-monitoring
@@ -58,7 +58,7 @@ The following steps show you how to configure the Radius control plane to send d
    kubectl port-forward svc/tracing 16686 -n radius-monitoring
    ```
 
-2. In your browser, go to [http://localhost:16686](http://localhost:16686) to see the Jaeger UI:
+1. In your browser, go to [http://localhost:16686](http://localhost:16686) to see the Jaeger UI:
 
    {{< image src="jaeger_ui.png" alt="" style="width:100%" >}}