Improve markdown formatting consistency

- Add alt text to image tags in README.md for accessibility - Convert indented numbered lists to consistent format in guide.md - Change shell snippets to use ```shell instead of ```bash - Harmonize headers level across various markdown documents - Adjust tables alignment for readability - Refactor list and header structure to improve readability and consistency
coder · matifali · Jan 3, 2025 · Nov 25, 2024 · Nov 25, 2024 · Nov 25, 2024
commit 60a5a4a8bb0790d5a3f77cd7403b90bfe41f3ddb
diff --git a/.github/workflows/docs-ci.yaml b/.github/workflows/docs-ci.yaml
@@ -32,4 +32,5 @@ jobs:
       - name: fmt
         if: steps.changed-files.outputs.any_changed == 'true'
         run: |
+          # markdown-table-formatter requires a space separated list of files
           echo ${{ steps.changed-files.outputs.all_changed_files }} | tr ',' '\n' | pnpm exec markdown-table-formatter --check
diff --git a/README.md b/README.md
@@ -1,20 +1,20 @@
 <div align="center">
   <a href="https://coder.com#gh-light-mode-only">
-    <img src="./docs/images/logo-black.png" style="width: 128px">
+    <img src="./docs/images/logo-black.png" alt="Coder Logo Light" style="width: 128px">
   </a>
   <a href="https://coder.com#gh-dark-mode-only">
-    <img src="./docs/images/logo-white.png" style="width: 128px">
+    <img src="./docs/images/logo-white.png" alt="Coder Logo Dark" style="width: 128px">
   </a>
 
   <h1>
   Self-Hosted Cloud Development Environments
   </h1>
 
   <a href="https://coder.com#gh-light-mode-only">
-    <img src="./docs/images/banner-black.png" style="width: 650px">
+    <img src="./docs/images/banner-black.png" alt="Coder Banner Light" style="width: 650px">
   </a>
   <a href="https://coder.com#gh-dark-mode-only">
-    <img src="./docs/images/banner-white.png" style="width: 650px">
+    <img src="./docs/images/banner-white.png" alt="Coder Banner Dark" style="width: 650px">
   </a>
 
   <br>
@@ -40,14 +40,14 @@
 - Onboard developers in seconds instead of days
 
 <p align="center">
-  <img src="./docs/images/hero-image.png">
+  <img src="./docs/images/hero-image.png" alt="Coder Hero Image">
 </p>
 
 ## Quickstart
 
 The most convenient way to try Coder is to install it on your local machine and experiment with provisioning cloud development environments using Docker (works on Linux, macOS, and Windows).
 
-```
+```shell
 # First, install Coder
 curl -L https://coder.com/install.sh | sh
 
@@ -65,7 +65,7 @@ The easiest way to install Coder is to use our
 and macOS. For Windows, use the latest `..._installer.exe` file from GitHub
 Releases.
 
-```bash
+```shell
 curl -L https://coder.com/install.sh | sh
 ```
 

diff --git a/SECURITY.md b/SECURITY.md
@@ -8,21 +8,21 @@ to us, what we expect, what you can expect from us.
 
 You can see the pretty version [here](https://coder.com/security/policy)
 
-# Why Coder's security matters
+## Why Coder's security matters
 
 If an attacker could fully compromise a Coder installation, they could spin up
 expensive workstations, steal valuable credentials, or steal proprietary source
 code. We take this risk very seriously and employ routine pen testing,
 vulnerability scanning, and code reviews. We also welcome the contributions from
 the community that helped make this product possible.
 
-# Where should I report security issues?
+## Where should I report security issues?
 
 Please report security issues to security@coder.com, providing all relevant
 information. The more details you provide, the easier it will be for us to
 triage and fix the issue.
 
-# Out of Scope
+## Out of Scope
 
 Our primary concern is around an abuse of the Coder application that allows an
 attacker to gain access to another users workspace, or spin up unwanted
@@ -40,7 +40,7 @@ workspaces.
   out-of-scope systems should be reported to the appropriate vendor or
   applicable authority.
 
-# Our Commitments
+## Our Commitments
 
 When working with us, according to this policy, you can expect us to:
 
@@ -53,7 +53,7 @@ When working with us, according to this policy, you can expect us to:
 - Extend Safe Harbor for your vulnerability research that is related to this
   policy.
 
-# Our Expectations
+## Our Expectations
 
 In participating in our vulnerability disclosure program in good faith, we ask
 that you:

diff --git a/coderd/rbac/README.md b/coderd/rbac/README.md
@@ -36,7 +36,7 @@ Both **negative** and **positive** permissions override **abstain** at the same
 This can be represented by the following truth table, where Y represents _positive_, N represents _negative_, and \_ represents _abstain_:
 
 | Action | Positive | Negative | Result |
-| ------ | -------- | -------- | ------ |
+|--------|----------|----------|--------|
 | read   | Y        | \_       | Y      |
 | read   | Y        | N        | N      |
 | read   | \_       | \_       | \_     |
@@ -63,10 +63,10 @@ This can be represented by the following truth table, where Y represents _positi
 A _role_ is a set of permissions. When evaluating a role's permission to form an action, all the relevant permissions for the role are combined at each level. Permissions at a higher level override permissions at a lower level.
 
 The following table shows the per-level role evaluation.
-Y indicates that the role provides positive permissions, N indicates the role provides negative permissions, and _ indicates the role does not provide positive or negative permissions. YN_ indicates that the value in the cell does not matter for the access result.
+Y indicates that the role provides positive permissions, N indicates the role provides negative permissions, and _indicates the role does not provide positive or negative permissions. YN_ indicates that the value in the cell does not matter for the access result.
 
 | Role (example)  | Site | Org  | User | Result |
-| --------------- | ---- | ---- | ---- | ------ |
+|-----------------|------|------|------|--------|
 | site-admin      | Y    | YN\_ | YN\_ | Y      |
 | no-permission   | N    | YN\_ | YN\_ | N      |
 | org-admin       | \_   | Y    | YN\_ | Y      |
@@ -102,7 +102,7 @@ Example of a scope for a workspace agent token, using an `allow_list` containing
     }
 ```
 
-# Testing
+## Testing
 
 You can test outside of golang by using the `opa` cli.
 

diff --git a/coderd/rbac/USAGE.md b/coderd/rbac/USAGE.md
@@ -1,6 +1,6 @@
 # Using RBAC
 
-# Overview
+## Overview
 
 > _NOTE: you should probably read [`README.md`](README.md) beforehand, but it's
 > not essential._
@@ -19,7 +19,7 @@ We have a number of roles (some of which have legacy connotations back to v1).
 These can be found in `coderd/rbac/roles.go`.
 
 | Role                 | Description                                                         | Example resources (non-exhaustive)           |
-| -------------------- | ------------------------------------------------------------------- | -------------------------------------------- |
+|----------------------|---------------------------------------------------------------------|----------------------------------------------|
 | **owner**            | Super-user, first user in Coder installation, has all\* permissions | all\*                                        |
 | **member**           | A regular user                                                      | workspaces, own details, provisioner daemons |
 | **auditor**          | Viewer of audit log events, read-only access to a few resources     | audit logs, templates, users, groups         |
@@ -43,7 +43,7 @@ Roles are collections of permissions (we call them _actions_).
 These can be found in `coderd/rbac/policy/policy.go`.
 
 | Action                  | Description                             |
-| ----------------------- | --------------------------------------- |
+|-------------------------|-----------------------------------------|
 | **create**              | Create a resource                       |
 | **read**                | Read a resource                         |
 | **update**              | Update a resource                       |
@@ -58,7 +58,7 @@ These can be found in `coderd/rbac/policy/policy.go`.
 | **stop**                | Stop a workspace                        |
 | **assign**              | Assign user to role / org               |
 
-# Creating a new noun
+## Creating a new noun
 
 In the following example, we're going to create a new RBAC noun for a new entity
 called a "frobulator" _(just some nonsense word for demonstration purposes)_.
@@ -291,7 +291,7 @@ frobulator, but no test case covered it.
 **NOTE: don't just add cases which make the tests pass; consider all the ways in
 which your resource must be used, and test all of those scenarios!**
 
-# Database authorization
+## Database authorization
 
 Now that we have the RBAC system fully configured, we need to make use of it.
 
@@ -350,7 +350,7 @@ before we validate (this explains the `fetchWithPostFilter` naming).
 All queries are executed through `dbauthz`, and now our little frobulators are
 protected!
 
-# API authorization
+## API authorization
 
 API authorization is not strictly required because we have database
 authorization in place, but it's a good practice to reject requests as soon as

diff --git a/dogfood/contents/guide.md b/dogfood/contents/guide.md
@@ -21,12 +21,12 @@ The following explains how to do certain things related to dogfooding.
 
 ### Run Coder in your Coder Workspace
 
-1.  Clone the Git repo
+1. Clone the Git repo
     `[https://github.com/coder/coder](https://github.com/coder/coder)` and `cd`
     into it
-2.  Run `sudo apt update` and then `sudo apt install -y netcat`
+2. Run `sudo apt update` and then `sudo apt install -y netcat`
     - skip this step if using the `coder` template
-3.  Run `make bin`
+3. Run `make bin`
 
     <aside>
     💡 If you run into the following error:
@@ -49,20 +49,20 @@ The following explains how to do certain things related to dogfooding.
     8. Try `make bin` again.
     </aside>
 
-4.  Run `./scripts/develop.sh` which will start _two_ separate processes:
+4. Run `./scripts/develop.sh` which will start _two_ separate processes:
     1. `[http://localhost:3000](http://localhost:3000)` — backend API server
        👈 Backend devs will want to talk to this
     2. `[http://localhost:8080](http://localhost:8080)` — Node.js dev server
        👈 Frontend devs will want to talk to this
-5.  Ensure that you’re logged in: `./scripts/coder-dev.sh list` — should return
+5. Ensure that you’re logged in: `./scripts/coder-dev.sh list` — should return
     no workspace. If this returns an error, double-check the output of running
     `scripts/develop.sh`.
-6.  A template named `docker-amd64` (or `docker-arm64` if you’re on ARM) will
+6. A template named `docker-amd64` (or `docker-arm64` if you’re on ARM) will
     have automatically been created for you. If you just want to create a
     workspace quickly, you can run
     `./scripts/coder-dev.sh create myworkspace -t docker-amd64` and this will
     get you going quickly!
-7.  To create your own template, you can do:
+7. To create your own template, you can do:
     `./scripts/coder-dev.sh templates init` and choose your preferred option.
     For example, choosing “Develop in Docker” will create a new folder `docker`
     that contains the bare bones for starting a Docker workspace template. Then,
@@ -75,7 +75,7 @@ The following explains how to do certain things related to dogfooding.
 
 ## Troubleshooting
 
-### My Docker containers keep failing and I have no idea what's going on!
+### My Docker containers keep failing and I have no idea what's going on
 
 ```console
 ✔ Queued [236ms]

diff --git a/examples/jfrog/docker/README.md b/examples/jfrog/docker/README.md
@@ -20,7 +20,7 @@ Edit the `Dockerfile` and run `coder templates push` to update workspaces.
 resource block. The `coder_app` resource is defined to access `code-server` through
 the dashboard UI over `localhost:13337`.
 
-# Next steps
+## Next steps
 
 Check out our [Docker](../../templates/docker/) template for a more fully featured Docker
 example.
diff --git a/examples/templates/kubernetes-envbox/README.md b/examples/templates/kubernetes-envbox/README.md
@@ -20,7 +20,7 @@ It mainly acts as a wrapper for the excellent [sysbox runtime](https://github.co
 The following environment variables can be used to configure various aspects of the inner and outer container.
 
 | env                        | usage                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | required |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
 | `CODER_INNER_IMAGE`        | The image to use for the inner container.                                                                                                                                                                                                                                                                                                                                                                                                                                       | True     |
 | `CODER_INNER_USERNAME`     | The username to use for the inner container.                                                                                                                                                                                                                                                                                                                                                                                                                                    | True     |
 | `CODER_AGENT_TOKEN`        | The [Coder Agent](https://coder.com/docs/about/architecture#agents) token to pass to the inner container.                                                                                                                                                                                                                                                                                                                                                                       | True     |

diff --git a/examples/workspace-tags/README.md b/examples/workspace-tags/README.md
@@ -5,17 +5,17 @@ tags: [local, docker, workspace-tags]
 icon: /icon/docker.png
 ---
 
-# Overview
+## Overview
 
 This Coder template presents use of [Workspace Tags](https://coder.com/docs/templates/workspace-tags) [Coder Parameters](https://coder.com/docs/templates/parameters).
 
-# Use case
+## Use case
 
 Template administrators can use static tags to control workspace provisioning, limiting it to specific provisioner groups. However, this restricts workspace users from choosing their preferred workspace nodes.
 
 By using `coder_workspace_tags` and `coder_parameter`s, template administrators can allow dynamic tag selection, avoiding the need to push the same template multiple times with different tags.
 
-    # Notes
+## Notes
 
 - You will need to have an [external provisioner](https://coder.com/docs/admin/provisioners#external-provisioners) with the correct tagset running in order to import this template.
 - When specifying values for the `coder_workspace_tags` data source, you are restricted to using a subset of Terraform's capabilities.
@@ -27,7 +27,7 @@ See [Workspace Tags](https://coder.com/docs/templates/workspace-tags) for more i
 
 Update the template and push it using the following command:
 
-```
+```shell
 ./scripts/coder-dev.sh templates push examples-workspace-tags \
   -d examples/workspace-tags \
   -y

diff --git a/helm/provisioner/README.md b/helm/provisioner/README.md
@@ -135,7 +135,7 @@ provisionerDaemon:
 nameOverride: "other-coder-provisioner"
 ```
 
-# Testing
+## Testing
 
 The test suite for this chart lives in `./tests/chart_test.go`.
 

diff --git a/package.json b/package.json
@@ -4,8 +4,8 @@
 	"version": "0.0.0",
 	"packageManager": "pnpm@9.14.4",
 	"scripts": {
-		"format-docs": "markdown-table-formatter './docs/**/*.md'",
-		"lint-docs": "markdownlint-cli2 --fix './docs/**/*.md'",
+		"format-docs": "markdown-table-formatter './**/*.md !**/node_modules/** !**/.terraform/**'",
+		"lint-docs": "markdownlint-cli2 --fix './**/*.md' '!**/node_modules/**' '!**/.terraform/**'",
 		"storybook": "pnpm run -C site/ storybook"
 	},
 	"devDependencies": {

diff --git a/scaletest/README.md b/scaletest/README.md
@@ -25,7 +25,7 @@ $ scaletest.sh --help
 Usage: scaletest.sh --name <name> --project <project> --num-workspaces <num-workspaces> --scenario <scenario> [--dry-run] [--skip-cleanup]
 ```
 
-### Required arguments:
+### Required arguments
 
 - `--name`: Name for the loadtest. This is added as a prefix to resources created by Terraform (e.g. `joe-big-loadtest`).
 - `--project`: Google Cloud project in which to create the resources (example: `my-loadtest-project`).
@@ -35,7 +35,7 @@ Usage: scaletest.sh --name <name> --project <project> --num-workspaces <num-work
 > **Note:** In order to capture Prometheus metrics, you must define the environment variables
 > `SCALETEST_PROMETHEUS_REMOTE_WRITE_USER` and `SCALETEST_PROMETHEUS_REMOTE_WRITE_PASSWORD`.
 
-### Optional arguments:
+### Optional arguments
 
 - `--dry-run`: Do not perform any action and instead print what would be executed.
 - `--skip-cleanup`: Do not perform any cleanup. You will be responsible for deleting any resources this creates.
@@ -62,7 +62,7 @@ A number of existing scenarios are provided in `scaletest/terraform/scenario-*.t
 
 For example, `scenario-small.tfvars` includes the following variable definitions:
 
-```
+```hcl
 nodepool_machine_type_coder      = "t2d-standard-2"
 nodepool_machine_type_workspaces = "t2d-standard-2"
 coder_cpu                        = "1000m" # Leaving 1 CPU for system workloads

diff --git a/scripts/releasemigrations/README.md b/scripts/releasemigrations/README.md
@@ -2,9 +2,9 @@
 
 The `main.go` is a program that lists all releases and which migrations are contained with each upgrade.
 
-# Usage
+## Usage
 
-```bash
+```shell
 releasemigrations [--patches] [--minors] [--majors]
   -after-v2
         Only include releases after v2.0.0
@@ -22,13 +22,13 @@ releasemigrations [--patches] [--minors] [--majors]
         Comma separated list of versions to use. This skips uses git tag to find tags.
 ```
 
-# Examples
+## Examples
 
-## Find all migrations between 2 versions
+### Find all migrations between 2 versions
 
 Going from 2.3.0 to 2.4.0
 
-```bash
+```shell
 $ go run scripts/releasemigrations/main.go --list --versions=v2.3.0,v2.4.0                                                                                                       11:47:00 AM
 2023/11/21 11:47:09 [minor] 4 migrations added between v2.3.0 and v2.4.0
 2023/11/21 11:47:09     coderd/database/migrations/000165_prevent_autostart_days.up.sql
@@ -42,7 +42,7 @@ $ go run scripts/releasemigrations/main.go --list --versions=v2.3.0,v2.4.0
 
 ## Looking at all patch releases after v2
 
-```bash
+```shell
 $ go run scripts/releasemigrations/main.go --patches --after-v2                                                                                                                  11:47:09 AM
 2023/11/21 11:48:00 [patch] No migrations added between v2.0.0 and v2.0.1
 2023/11/21 11:48:00 [patch] 2 migrations added between v2.0.1 and v2.0.2
@@ -63,7 +63,7 @@ $ go run scripts/releasemigrations/main.go --patches --after-v2
 
 This shows when every migration was introduced.
 
-```bash
+```shell
 $ go run scripts/releasemigrations/main.go --patches --minors --majors --list
 # ...
 2023/11/21 11:48:31 [minor] 5 migrations added between v2.2.1 and v2.3.0