fix(docs): move TOC to the right nav bar to free up vertical space

runatlantis · May 14, 2024 · f466387 · f466387
1 parent 5fafbb1
commit f466387
Show file tree

Hide file tree

Showing 17 changed files with 819 additions and 291 deletions.
diff --git a/runatlantis.io/.vitepress/config.ts b/runatlantis.io/.vitepress/config.ts
@@ -1,6 +1,6 @@
-import { defineConfig } from 'vitepress';
-import * as navbars from "./navbars";
-import * as sidebars from "./sidebars";
+import { defineConfig } from 'vitepress'
+import * as navbars from "./navbars"
+import * as sidebars from "./sidebars"
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -23,6 +23,10 @@ export default defineConfig({
         editLink: {
             pattern: 'https://github.com/runatlantis/atlantis/edit/main/runatlantis.io/:path'
         },
+        // headline "depth" the right nav will show for its TOC
+        //
+        // https://vitepress.dev/reference/frontmatter-config#outline
+        outline: [2, 3],
         search: {
             provider: 'algolia',
             options: {
@@ -45,9 +49,9 @@ export default defineConfig({
             }
         },
         socialLinks: [
-          { icon: "slack", link: "https://join.slack.com/t/atlantis-community/shared_invite/zt-9xlxtxtc-CUSKB1ATt_sQy6um~LDPNw" },
-          { icon: "twitter", link: "https://twitter.com/runatlantis" },
-          { icon: "github", link: "https://github.com/runatlantis/atlantis" },
+            { icon: "slack", link: "https://join.slack.com/t/atlantis-community/shared_invite/zt-9xlxtxtc-CUSKB1ATt_sQy6um~LDPNw" },
+            { icon: "twitter", link: "https://twitter.com/runatlantis" },
+            { icon: "github", link: "https://github.com/runatlantis/atlantis" },
         ],
     },
     head: [

diff --git a/runatlantis.io/docs/access-credentials.md b/runatlantis.io/docs/access-credentials.md
@@ -1,10 +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.
-[[toc]]
 
 ## 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
@@ -14,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)
@@ -25,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 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)
@@ -36,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).
 
@@ -59,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).
 
@@ -93,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
+* 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 "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
+* 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 **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
+* 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).