fix(docs): add markdownlint and apply rules (#4557)

runatlantis · May 14, 2024 · 6fe0303 · 6fe0303
1 parent ee103c3
commit 6fe0303
Show file tree

Hide file tree

Showing 42 changed files with 1,060 additions and 388 deletions.
diff --git a/.editorconfig b/.editorconfig
@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+indent_style = space
+indent_size = 3
+trim_trailing_whitespace = false
diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml
@@ -48,6 +48,12 @@ jobs:
     steps:
       - uses: actions/checkout@0ad4b8fadaa221de15dcec353f45205ec38ea70b # v4
 
+      - name: markdown-lint
+        uses: DavidAnson/markdownlint-cli2-action@b4c9feab76d8025d1e83c653fa3990936df0e6c8 # v16
+        with:
+          config: .markdownlint.yaml
+          globs: 'runatlantis.io/**/*.md'
+
       - uses: wyvox/action-setup-pnpm@6597ef5c1300fe08efa6bc75e6141f7153e2b4cc # v3
         with:
           node-version: 20

diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -0,0 +1,33 @@
+# MD013/line-length
+#
+# We're not particular about line length, generally preferring longer
+# lines, since tools like Grammarly and other writing assistance tools
+# work best with "normal" lines not broken up arbitrary.
+#
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
+MD013: false
+
+# MD033/no-inline-html
+#
+# We're fine with inline HTML, there are lots of valid VitePress features
+# that depends on this.
+#
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/md033.md
+MD033: false
+
+# MD024/no-duplicate-heading
+#
+# VitePress do not follow GitHub heading styling, so duplicate headlines
+# are fine as long as they are not siblings (aka same indention hierarchy)
+#
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/md024.md
+MD024:
+  siblings_only: true
+
+# MD051/link-fragments
+#
+# VitePress generate these differently that markdownlint expects, so disabling
+# for now, and something to improve on later (cc @jippi)
+#
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md
+MD051: false
diff --git a/package.json b/package.json
@@ -8,10 +8,13 @@
     "sass": "^1.77.0",
     "sitemap-ts": "^1.6.1",
     "vitepress": "^1.1.4",
-    "vue": "^3.4.27"
+    "vue": "^3.4.27",
+    "markdownlint-cli": "^0.40.0"
   },
   "scripts": {
     "website:dev": "vitepress dev --host localhost --port 8080 runatlantis.io",
+    "website:lint": "markdownlint runatlantis.io",
+    "website:lint-fix": "markdownlint --fix runatlantis.io",
     "website:build": "vitepress build runatlantis.io",
     "e2e": "playwright test"
   }

diff --git a/runatlantis.io/contributing.md b/runatlantis.io/contributing.md
@@ -1,3 +1,6 @@
+---
+aside: false
+---
 # Atlantis Contributing Documentation
 
 These docs are for users who want to contribute to the Atlantis project. This
@@ -9,6 +12,6 @@ If you're new, check out the [Guide](./guide.md) or the
 [Documentation](./docs.md).
 :::
 
-### Next Steps
+## Next Steps
 
 - [Events Controller](./contributing/events-controller.md)&nbsp;&nbsp;–&nbsp;&nbsp;How do the events work?
diff --git a/runatlantis.io/contributing/events-controller.md b/runatlantis.io/contributing/events-controller.md
@@ -51,6 +51,7 @@ documentation.
 - [GitHub Pull Request](https://docs.github.com/en/webhooks/webhook-events-and-payloads#pull_request)
 - [GitLab Merge Request](https://docs.gitlab.com/ee/user/project/integrations/webhook_events.html#merge-request-events)
 - [Gitea Webhooks](https://docs.gitea.com/next/usage/webhooks)
+
 </details>
 
 The following list shows the supported events:

diff --git a/runatlantis.io/docs.md b/runatlantis.io/docs.md
@@ -1,3 +1,6 @@
+---
+aside: false
+---
 # Atlantis Documentation
 
 These docs are for users that are ready to get Atlantis installed and start using it.
@@ -7,7 +10,7 @@ If you're new here, check out the [Guide](./guide.md)
 where you can try our [Test Drive](./guide/test-drive.md) or [Run Atlantis Locally](./guide/testing-locally.md).
 :::
 
-### Next Steps
+## Next Steps
 
 * [Installing Atlantis](./docs/installation-guide.md)&nbsp;&nbsp;–&nbsp;&nbsp;Get Atlantis up and running
 * [Configuring Atlantis](./docs/configuring-atlantis.md)&nbsp;&nbsp;–&nbsp;&nbsp;Configure how Atlantis works for your specific use-cases

diff --git a/runatlantis.io/docs/access-credentials.md b/runatlantis.io/docs/access-credentials.md
@@ -1,9 +1,11 @@
 # Git Host Access Credentials
+
 This page describes how to create credentials for your Git host (GitHub, GitLab, Gitea, Bitbucket, or Azure DevOps)
 
 that Atlantis will use to make API calls.
 
 ## Create an Atlantis user (optional)
+
 We recommend creating a new user named **@atlantis** (or something close) or using a dedicated CI user.
 
 This isn't required (you can use an existing user or github app credentials), however all the comments that Atlantis writes
@@ -13,8 +15,10 @@ will come from that user so it might be confusing if its coming from a personal
 <p align="center"><i>An example comment coming from the @atlantisbot user</i></p>
 
 ## Generating an Access Token
+
 Once you've created a new user (or decided to use an existing one), you need to
 generate an access token. Read on for the instructions for your specific Git host:
+
 * [GitHub](#github-user)
 * [GitHub app](#github-app)
 * [GitLab](#gitlab)
@@ -24,9 +28,10 @@ generate an access token. Read on for the instructions for your specific Git hos
 * [Azure DevOps](#azure-devops)
 
 ### GitHub user
-- Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)
-- Create the token with **repo** scope
-- Record the access token
+
+* Create a [Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token#creating-a-fine-grained-personal-access-token)
+* Create the token with **repo** scope
+* Record the access token
 ::: warning
 Your Atlantis user must also have "Write permissions" (for repos in an organization) or be a "Collaborator" (for repos in a user account) to be able to set commit statuses:
 ![Atlantis status](./images/status.png)
@@ -35,16 +40,16 @@ Your Atlantis user must also have "Write permissions" (for repos in an organizat
 ### GitHub app
 
 #### Create the GitHub App Using Atlantis
+
 ::: warning
 Available in Atlantis versions **newer** than 0.13.0.
 :::
 
-
-- Start Atlantis with fake github username and token (`atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`). If installing as an **Organization**, remember to add `--gh-org your-github-org` to this command.
-- Visit `https://$ATLANTIS_HOST/github-app/setup` and click on **Setup** to create the app on GitHub. You'll be redirected back to Atlantis
-- A link to install your app, along with its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link.
-- Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem`
-- Restart Atlantis with new flags: `atlantis server --gh-app-id <your id> --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret <your secret> --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`.
+* Start Atlantis with fake github username and token (`atlantis server --gh-user fake --gh-token fake --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`). If installing as an **Organization**, remember to add `--gh-org your-github-org` to this command.
+* Visit `https://$ATLANTIS_HOST/github-app/setup` and click on **Setup** to create the app on GitHub. You'll be redirected back to Atlantis
+* A link to install your app, along with its secrets, will be shown on the screen. Record your app's credentials and install your app for your user/org by following said link.
+* Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem`
+* Restart Atlantis with new flags: `atlantis server --gh-app-id <your id> --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret <your secret> --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`.
 
   NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file).
 
@@ -58,11 +63,11 @@ GitHub App handles the webhook calls by itself, hence there is no need to create
 
 #### Manually Creating the GitHub app
 
-- Create the GitHub app as an Administrator
-  - Ensure the app is registered / installed with the organization / user
-  - See the GitHub app [documentation](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)
-- Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem`
-- Start Atlantis with the following flags: `atlantis server --gh-app-id <your id> --gh-installation-id <installation id> --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret <your secret> --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`.
+* Create the GitHub app as an Administrator
+  * Ensure the app is registered / installed with the organization / user
+  * See the GitHub app [documentation](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps)
+* Create a file with the contents of the GitHub App Key, e.g. `atlantis-app-key.pem`
+* Start Atlantis with the following flags: `atlantis server --gh-app-id <your id> --gh-installation-id <installation id> --gh-app-key-file atlantis-app-key.pem --gh-webhook-secret <your secret> --write-git-creds --repo-allowlist 'github.com/your-org/*' --atlantis-url https://$ATLANTIS_HOST`.
 
   NOTE: Instead of using a file for the GitHub App Key you can also pass the key value directly using `--gh-app-key`. You can also create a config file instead of using flags. See [Server Configuration](server-configuration.md#config-file).
 
@@ -92,56 +97,62 @@ Since v0.19.7, a new permission for `Administration` has been added. If you have
 Since v0.22.3, a new permission for `Members` has been added, which is required for features that apply permissions to an organizations team members rather than individual users. Like the `Administration` permission above, updating Atlantis will not automatically add this permission, so if you wish to use features that rely on checking team membership you will need to add this manually.
 :::
 
-| Type            | Access              | 
-| --------------- | ------------------- | 
-| Administration  | Read-only           | 
-| Checks          | Read and write      | 
-| Commit statuses | Read and write      | 
-| Contents        | Read and write      | 
-| Issues          | Read and write      | 
-| Metadata        | Read-only (default) | 
-| Pull requests   | Read and write      | 
-| Webhooks        | Read and write      | 
-| Members         | Read-only           | 
+| Type            | Access              |
+| --------------- | ------------------- |
+| Administration  | Read-only           |
+| Checks          | Read and write      |
+| Commit statuses | Read and write      |
+| Contents        | Read and write      |
+| Issues          | Read and write      |
+| Metadata        | Read-only (default) |
+| Pull requests   | Read and write      |
+| Webhooks        | Read and write      |
+| Members         | Read-only           |
 
 ### GitLab
-- Follow: [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token)
-- Create a token with **api** scope
-- Record the access token
+
+* Follow: [GitLab: Create a personal access token](https://docs.gitlab.com/ce/user/profile/personal_access_tokens.html#create-a-personal-access-token)
+* Create a token with **api** scope
+* Record the access token
 
 ### Gitea
-- Go to "Profile and Settings" > "Settings" in Gitea (top-right)
-- Go to "Applications" under "User Settings" in Gitea
-- Create a token under the "Manage Access Tokens" with the following permissions:
-  - issue: Read and Write
-  - repository: Read and Write
-  - user: Read
-- Record the access token
+
+* Go to "Profile and Settings" > "Settings" in Gitea (top-right)
+* Go to "Applications" under "User Settings" in Gitea
+* Create a token under the "Manage Access Tokens" with the following permissions:
+  * issue: Read and Write
+  * repository: Read and Write
+  * user: Read
+* Record the access token
 
 ### Bitbucket Cloud (bitbucket.org)
-- Create an App Password by following [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/)
-- Label the password "atlantis"
-- Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
-- Record the access token
+
+* Create an App Password by following [BitBucket Cloud: Create an app password](https://support.atlassian.com/bitbucket-cloud/docs/create-an-app-password/)
+* Label the password "atlantis"
+* Select **Pull requests**: **Read** and **Write** so that Atlantis can read your pull requests and write comments to them
+* Record the access token
 
 ### Bitbucket Server (aka Stash)
-- Click on your avatar in the top right and select **Manage account**
-- Click **Personal access tokens** in the sidebar
-- Click **Create a token**
-- Name the token **atlantis**
-- Give the token **Read** Project permissions and **Write** Pull request permissions
-- Click **Create** and record the access token
+
+* Click on your avatar in the top right and select **Manage account**
+* Click **Personal access tokens** in the sidebar
+* Click **Create a token**
+* Name the token **atlantis**
+* Give the token **Read** Project permissions and **Write** Pull request permissions
+* Click **Create** and record the access token
 
   NOTE: Atlantis will send the token as a [Bearer Auth to the Bitbucket API](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html#HTTPaccesstokens-UsingHTTPaccesstokens) instead of using Basic Auth.
 
 ### Azure DevOps
-- Create a Personal access token by following [Azure DevOps: Use personal access tokens to authenticate](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops)
-- Label the password "atlantis"
-- The minimum scopes required for this token are:
-  - Code (Read & Write)
-  - Code (Status)
-  - Member Entitlement Management (Read)
-- Record the access token
+
+* Create a Personal access token by following [Azure DevOps: Use personal access tokens to authenticate](https://docs.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops)
+* Label the password "atlantis"
+* The minimum scopes required for this token are:
+  * Code (Read & Write)
+  * Code (Status)
+  * Member Entitlement Management (Read)
+* Record the access token
 
 ## Next Steps
+
 Once you've got your user and access token, you're ready to create a webhook secret. See [Creating a Webhook Secret](webhook-secrets.md).
diff --git a/runatlantis.io/docs/api-endpoints.md b/runatlantis.io/docs/api-endpoints.md
@@ -21,18 +21,18 @@ Execute [atlantis plan](using-atlantis.md#atlantis-plan) on the specified reposi
 
 #### Parameters
 
-| Name       | Type                              | Required | Description                              |
-|------------|-----------------------------------|----------|------------------------------------------|
-| Repository | string                            | Yes      | Name of the Terraform repository         |
-| Ref        | string                            | Yes      | Git reference, like a branch name        |
-| Type       | string                            | Yes      | Type of the VCS provider (Github/Gitlab) |
-| Paths      | [ [Path](api-endpoints.md#path) ] | Yes      | Paths to the projects to run the plan    |
-| PR         | int                               | No       | Pull Request number                      |
+| Name       | Type    | Required | Description                              |
+|------------|---------|----------|------------------------------------------|
+| Repository | string  | Yes      | Name of the Terraform repository         |
+| Ref        | string  | Yes      | Git reference, like a branch name        |
+| Type       | string  | Yes      | Type of the VCS provider (Github/Gitlab) |
+| Paths      | Path    | Yes      | Paths to the projects to run the plan    |
+| PR         | int     | No       | Pull Request number                      |
 
-##### Path
+#### Path
 
 Similar to the [Options](using-atlantis.md#options) of `atlantis plan`. Path specifies which directory/workspace
-within the repository to run the plan.  
+within the repository to run the plan.
 At least one of `Directory` or `Workspace` should be specified.
 
 | Name      | Type   | Required | Description                                                                                                                                               |
@@ -96,18 +96,18 @@ Execute [atlantis apply](using-atlantis.md#atlantis-apply) on the specified repo
 
 #### Parameters
 
-| Name       | Type                                | Required | Description                              |
-|------------|-------------------------------------|----------|------------------------------------------|
-| Repository | string                              | Yes      | Name of the Terraform repository         |
-| Ref        | string                              | Yes      | Git reference, like a branch name        |
-| Type       | string                              | Yes      | Type of the VCS provider (Github/Gitlab) |
-| Paths      | [ [Path](api-endpoints.md#path-1) ] | Yes      | Paths to the projects to run the apply   |
-| PR         | int                                 | No       | Pull Request number                      |
+| Name       | Type   | Required | Description                              |
+|------------|--------|----------|------------------------------------------|
+| Repository | string | Yes      | Name of the Terraform repository         |
+| Ref        | string | Yes      | Git reference, like a branch name        |
+| Type       | string | Yes      | Type of the VCS provider (Github/Gitlab) |
+| Paths      | Path   | Yes      | Paths to the projects to run the apply   |
+| PR         | int    | No       | Pull Request number                      |
 
-##### Path
+#### Path
 
 Similar to the [Options](using-atlantis.md#options-1) of `atlantis apply`. Path specifies which directory/workspace
-within the repository to run the apply.  
+within the repository to run the apply.
 At least one of `Directory` or `Workspace` should be specified.
 
 | Name      | Type   | Required | Description                                                                                                                                               |