docs: update docs + docs CI (#505)

.github/workflows/docs.yaml

@@ -3,8 +3,15 @@ on:
   push:
     branches:
       - main
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+
 permissions:
   contents: write
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
@@ -15,9 +22,22 @@ jobs:
           python-version: 3.x
       - uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4
         with:
-          key: mkdocs-material-${{ github.sha }}
+          key: mkdocs-material-${{ github.ref }}
           path: .cache
           restore-keys: |
             mkdocs-material-
+
       - run: pip install mkdocs-material
-      - run: mkdocs gh-deploy --force
+
+      - name: Lint Markdown files
+        uses: DavidAnson/markdownlint-cli2-action@v19
+        with:
+          config: 'docs/.markdownlint.jsonc'
+          globs: 'docs/**/*.md'
+
+      - name: Build pages
+        run: mkdocs build --strict
+
+      - name: Deploy pages
+        run: mkdocs gh-deploy --strict --force
+        if: github.ref == 'refs/heads/main'

docs/.markdownlint.jsonc

@@ -0,0 +1,7 @@
+{
+    "line-length": false,
+    "no-inline-html": false,
+    "no-alt-text": false,
+    "no-duplicate-heading": false,
+    "ul-indent": false
+}

docs/contributing.md

@@ -56,22 +56,25 @@ Follow these steps to install a minimal working configuration of Burrito on a Ki
 - A datastore running with mock storage (in-memory)
 - A `TerraformRepository` and an associated `TerraformLayer` resource in the `burrito-project` namespace, pointing to the [padok-team/burrito-examples](https://github.com/padok-team/burrito-examples) repository
 
-*Before starting, check that your local Kind cluster is running and that your context is set to target this cluster*
+*Before starting, check that your local Kind cluster is running and that your context is set to target this cluster.*
 
 1. **Install cert-manager on your cluster:**
-```bash
-helm repo add bitnami https://charts.bitnami.com/bitnami
-helm upgrade --install -n cert-manager --create-namespace cert-manager bitnami/cert-manager --set installCRDs=true
-```
+
+    ```bash
+    helm repo add bitnami https://charts.bitnami.com/bitnami
+    helm upgrade --install -n cert-manager --create-namespace cert-manager bitnami/cert-manager --set installCRDs=true
+    ```
+
 2. **Fork and clone this repository.**
 
 3. **Run the following command to build a local image of Burrito, load it into your Kind cluster, and install Burrito with development Helm values:**
-    
+
     ```bash
     make upgrade-dev-kind
     ```
 
 4. **Check that Burrito is running in the `burrito-system` namespace:**
+
     ```bash
     kubectl get pods -n burrito-system
     ```
@@ -134,7 +137,7 @@ helm upgrade --install -n cert-manager --create-namespace cert-manager bitnami/c
 
     The output should be similar to:
 
-    ```
+    ```text
     NAME                   READY   STATUS      RESTARTS   AGE
     my-layer-apply-gxjhd   0/1     Completed   0          2m36s
     ```
@@ -157,7 +160,7 @@ Check the [Makefile](https://github.com/padok-team/burrito/blob/main/Makefile) f
 
 ### Advanced Settings
 
-**Configure a GitHub Token for TENV**
+**Configure a GitHub Token for TENV:**
 
 It is strongly recommended to create a GitHub token with no specific rights to bypass the GitHub API rate limiting. Append the following configuration to your development `TerraformRepository` resources:
 

docs/getting-started.md

@@ -18,6 +18,7 @@ Copy and modify the [default values](https://github.com/padok-team/burrito/blob/
 Make sure to configure a tenant by updating the `tenant` field in the `values.yaml` file. The associated namespace will be created automatically and used to deploy Burrito resources in step 3.
 
 For example, here is a default `values.yaml` file:
+
 ```yaml
 config:
   datastore:
@@ -47,14 +48,18 @@ This will create a new namespace, `burrito-system`, where Burrito services will
 
 Create a Kubernetes `Secret` to reference the necessary credentials to clone your IaC repository (GitHub or GitLab)
 
+<!-- markdownlint-disable MD046 -->
 !!! info
     Supported authentication methods are:
+
     - Username and password
     - SSH private key
     - GitHub App
     - GitHub API token
     - GitLab API token
-    More information on how to create a secret can be found in the [Secrets](./secrets/index.md) section.
+
+    More information on how to create a secret can be found in the [Git Authentication](./operator-manual/git-authentication.md) section.
+<!-- markdownlint-enable MD046 -->
 
 ```yaml
 kind: Secret
@@ -116,4 +121,3 @@ The controller will create a runner pod in your tenant namespace to synchronize
 
 - For detailed guides on how to use Burrito, see the [Guides](./guides/index.md) section.
 - To learn more about advanced configuration and features, see the [Operator Manual](./operator-manual/index.md) section.
-

docs/guides/iac-drift-detection.md

@@ -48,7 +48,8 @@ kubectl get pods -n burrito-system
 ```
 
 Output:
-```
+
+```text
 NAME                                   READY   STATUS    RESTARTS   AGE
 burrito-controllers-6945797c5d-kjfl2   1/1     Running   0          2m00s
 burrito-datastore-94d999f54-kbg9z      1/1     Running   0          2m00s
@@ -82,7 +83,7 @@ spec:
     enabled: true
 ```
 
-Create a `TerraformLayer` resource in the `burrito-system` namespace, referencing the `TerraformRepository` you just created. For now, the `autoApply` is set to false, so the layer will only plan the Terraform code and not apply it. 
+Create a `TerraformLayer` resource in the `burrito-system` namespace, referencing the `TerraformRepository` you just created. For now, the `autoApply` is set to false, so the layer will only plan the Terraform code and not apply it.
 
 ```bash
 kubectl apply -f https://raw.githubusercontent.com/padok-team/burrito/main/docs/examples/terraform-layer.yaml
@@ -173,4 +174,4 @@ You have successfully set up Burrito on a local cluster and planned your Terrafo
 
 ## Next steps
 
-- Learn how to [configure a PR/MR workflow](../pr-mr-workflow.md)
+- Learn how to [configure a PR/MR workflow](../operator-manual/pr-mr-workflow.md)

docs/guides/index.md

@@ -1,7 +1,7 @@
 # Getting started
 
-Follow the 3 guides below to understand how to use Burrito: 
+Follow the 3 guides below to understand how to use Burrito:
 
 - [IaC Drift detection](./iac-drift-detection.md): Quickly set up Burrito and start monitoring Terraform state drift.
 - [PR/MR plan/apply Workflow](./pr-mr-workflow.md): Configure Burrito to automatically plan and apply Terraform code on PR/MR.
-- [UI Overview](./ui-overview.md): Learn how to navigate the Burrito UI.
+- [UI Overview](./ui.md): Learn how to navigate the Burrito UI.

docs/guides/pr-mr-workflow.md

@@ -37,6 +37,7 @@ Now let's configure the GitHub webhook. Expose the `burrito-server` kubernetes s
 Configure a webhook in your GitHub repository to point to the exposed `burrito-server` service. **Make sure to specify the `/api/webhook` path in the target url.** The webhook should be triggered on `push` and `pull_request` events. Reference your webhook secret in the secret associated to your repository, in the `webhookSecret` key.
 
 Your `TerraformRepository` resource and secret should look like this:
+
 ```yaml
 apiVersion: config.terraform.padok.cloud/v1alpha1
 kind: TerraformRepository
@@ -62,7 +63,7 @@ stringData:
     -----BEGIN RSA PRIVATE KEY-----
     my-private-key
     -----END RSA PRIVATE KEY-----
-  webhookSecret: "my-webhook-secret" 
+  webhookSecret: "my-webhook-secret"
 ```
 
 ### Experiment with the PR/MR workflow

docs/index.md

@@ -5,9 +5,8 @@ This is the home of the Burrito documentation. Here you will find all the inform
 - [Overview](./overview.md) helps you understand what Burrito is all about.
 - [Getting Started](./getting-started.md) is a step-by-step guide to help you get started with Burrito.
 - [Guides](./guides/index.md) provides detailed tutorials to help you understand how to use Burrito.
-- [Operator Manual](./operator-manual/) is a detailed guide to help you understand how to install and configure Burrito.
-- [User Guide](./user-guide/) is a detailed guide to help you understand how to setup and use Burrito resources.
+- [Operator Manual](./operator-manual/index.md) is a detailed guide to help you understand how to install and configure Burrito.
+- [User Guide](./user-guide/index.md) is a detailed guide to help you understand how to setup and use Burrito resources.
 - [Contributing](./contributing.md) provides information on how to contribute to the Burrito project.
 <!-- - [Reference](./reference/) provides detailed information about the Burrito CRDs and their specifications.
 - [FAQ](./faq.md) answers some of the most frequently asked questions about Burrito. -->
-

docs/installation/with-helm.md

@@ -31,7 +31,6 @@ helm show values oci://ghcr.io/padok-team/charts/burrito
 
 The [source code](https://github.com/padok-team/burrito/tree/main/deploy/charts/burrito) and [values file](https://github.com/padok-team/burrito/blob/main/deploy/charts/burrito/values.yaml) of the chart is available on [burrito GitHub repository](https://github.com/padok-team/burrito).
 
-
 Here is an example of a simple burrito Helm values file that you can use to bootstrap your installation:
 
 ```yaml

docs/installation/with-static-manifests.md

@@ -8,7 +8,7 @@
 ## Install burrito
 
 !!! info
-    This will install a mono-tenant version of burrito. See the [Helm installation method](./with-helm.md) for a [multi-tenant-architecture](../multi-tenant-architecture.md).
+    This will install a mono-tenant version of burrito. See the [Helm installation method](./with-helm.md) for a [multi-tenant-architecture](..//operator-manual/multi-tenant-architecture.md).
 
 ```bash
 kubectl create namespace burrito

docs/operator-manual/git-authentication.md

@@ -4,44 +4,53 @@
 
 This section will guide you through the different ways to authenticate to a git repository.
 Authentication is required for:
+
 - Cloning a private repository
 - Implementing the [PR/MR workflow](./pr-mr-workflow.md)
+- Setting up the webhook for listening to push / pull requests events
 
 Available authentication methods:
+
 - Username and password (only supports cloning)
 - SSH private key (only supports cloning)
-- GitHub App
+- [GitHub App](https://docs.github.com/en/apps)
 - GitHub API token
 - GitLab API token
 
 ## Repository Secret
 
 The `TerraformRepository` spec allows you to specify a secret that contains the credentials to authenticate to a git repository.
-The secret must be created in the same namespace as the `TerraformRepository` and be referenced in `spec.repository.secretName`.
+The secret must be created in the **same namespace** as the `TerraformRepository` and be referenced in `spec.repository.secretName`.
 
 ### Expected keys
 
 To add an authentication method for a repository, the secret must contain the following keys:
 
-Username and password:
+Username and password (Git's HTTPS authentication):
+
 - `username`
 - `password`
 
-SSH private key:
+SSH private key (Git's SSH authentication):
+
 - `sshPrivateKey`
 
 GitHub App:
+
 - `githubAppId`
 - `githubAppInstallationId`
 - `githubAppPrivateKey`
 
 GitHub API token:
+
 - `githubToken`
 
 GitLab API token:
+
 - `gitlabToken`
 
 For the PR/MR workflow, the Kubernetes secret must also contain the webhook secret:
+
 - `webhookSecret`
 
 Example of a Kubernetes secret for a GitHub repository, using authentication with a GitHub App and implementing the PR workflow:
@@ -60,7 +69,7 @@ stringData:
     -----BEGIN RSA PRIVATE KEY-----
     my-private-key
     -----END RSA PRIVATE KEY-----
-  webhookSecret: "my-webhook-secret" 
+  webhookSecret: "my-webhook-secret"
 ```
 
 ### Behavior

docs/operator-manual/multi-tenant-architecture.md

@@ -2,7 +2,7 @@
 
 <p align="center"><img src="../../assets/design/multi-tenant-architecture.excalidraw.png" width="1000px" /></p>
 
-With our [Helm chart](./install/with-helm.md) we provide a way to setup multi-tenancy with burrito. This is useful when working at scale, when you controls multiple Terraform projects with burrito across several teams.
+With our [Helm chart](../installation/with-helm.md) we provide a way to setup multi-tenancy with burrito. This is useful when working at scale, when you controls multiple Terraform projects with burrito across several teams.
 
 The setup is split across multiple Kubernetes namespaces:
 
@@ -15,7 +15,7 @@ Thanks to Kubernetes native RBAC system you can restrict access for your users o
 
 ### 1. Configure basic tenants
 
-In the `values.yaml` of the [Helm chart](./install/with-helm.md), add the following:
+In the `values.yaml` of the [Helm chart](../installation/with-helm.md), add the following:
 
 ```yaml
 tenants:

docs/operator-manual/pr-mr-workflow.md

@@ -49,6 +49,7 @@ With those 3 conditions, we defined 3 states:
 
 Follow the instructions in [Setting up a Git Webhook](./git-webhook.md) to configure a webhook in your repository.
 The webhook will be used to trigger:
+
 - Drift detection when a push event is received.
 - The PR/MR workflow when a pull request event is received.
 
@@ -61,11 +62,11 @@ You can create and register GitHub Apps in your personal GitHub account or in an
 Follow the instructions in the GitHub documentation on [Creating a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). Populate the settings as follows:
 
 - **GitHub App Name**: Choose a name for your GitHub App. For example, something featuring `burrito`.
-- **Homepage URL**: Enter https://padok-team.github.io/burrito.
-- **Webhook**: Deselect Active. The app doesn't use this webhook events mechanism at the moment.
-- **Permissions**: Configure the following **Repository Permissions**.
-  - **Metadata**: Select Read-only.
-  - **Pull requests**: Select Read & write. This is required to issue comments on pull requests.
+- **Homepage URL**: Enter <https://padok-team.github.io/burrito>.
+- **Webhook**: Unselect Active. The app doesn't use this webhook events mechanism at the moment.
+- **Permissions**: Configure the following **Repository Permissions**:
+    - **Metadata**: Select Read-only.
+    - **Pull requests**: Select Read & write. This is required to issue comments on pull requests.
 - Where can this GitHub App be installed: Select **Any account**.
 
 #### Creating a custom badge for your GitHub App
@@ -86,13 +87,12 @@ Follow the instructions in the GitHub documentation on [Installing your own GitH
 
 You need the **Installation ID** and **App ID** to configure Burrito.
 
+<!-- markdownlint-disable MD032 -->
 1. Get the **Installation ID** from the URL of the installed app, such as:
-
-<p align="center"><img src="../../assets/pr-mr-workflow/github_installation_id.png" /></p>
-
+  <p align="center"><img src="../../assets/pr-mr-workflow/github_installation_id.png" /></p>
 2. Get the **App ID** from the app's General tab.
-
-<p align="center"><img src="../../assets/pr-mr-workflow/github_app_id.png" /></p>
+  <p align="center"><img src="../../assets/pr-mr-workflow/github_app_id.png" /></p>
+<!-- markdownlint-enable MD032 -->
 
 #### Generate a private key
 
@@ -107,6 +107,7 @@ You need a private key for your GitHub app to configure Burrito.
 Add the credentials of your newly created app to the secret associated to your `TerraformRepository` resource. If the repository is public, create a secret in the same namespace as the `TerraformRepository` and reference it in the `spec.repository.secretName`.
 
 For example:
+
 ```yaml
 apiVersion: config.terraform.padok.cloud/v1alpha1
 kind: TerraformRepository
@@ -145,16 +146,17 @@ You need a personal access token to configure Burrito. You can generate a person
 Follow the instructions in the GitHub documentation for [creating a personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token):
 
 - It should be a **fine-grained token**.
-- **Permissions**: Configure the following **Repository Permissions**.
-  - **Metadata**: Select Read-only.
-  - **Pull requests**: Select Read & write. This is required to issue comments on pull requests.
+- **Permissions**: Configure the following **Repository Permissions**:
+    - **Metadata**: Select Read-only.
+    - **Pull requests**: Select Read & write. This is required to issue comments on pull requests.
 - Under **Repository access**, select which repositories you want the token to access.
 
 #### Configure Burrito
 
 Set the `githubToken` key in the secret associated to your `TerraformRepository` resource.
 
 For example:
+
 ```yaml
 apiVersion: config.terraform.padok.cloud/v1alpha1
 kind: TerraformRepository
@@ -188,8 +190,8 @@ You need a private token for your GitLab app to configure Burrito. You can gener
 
 Set the `gitlabToken` key in the secret associated to your `TerraformRepository` resource.
 
-
 For example:
+
 ```yaml
 apiVersion: config.terraform.padok.cloud/v1alpha1
 kind: TerraformRepository

docs/operator-manual/provider-caching.md

@@ -6,15 +6,15 @@ The Burrito Helm chart is packaged with [Hermitcrab](https://github.com/seal-io/
 
 ## 1. Activate Hermitcrab on Burrito
 
-Hermitcrab is available to use with Burrito when using the Helm chart.  
+Hermitcrab is available to use with Burrito when using the Helm chart.
 Set the `config.burrito.hermitcrab` parameter to true in your values file to activate Hermitcrab.
 
 As the Provider Network Mirror Protocol only supports HTTPS traffic, it is required to provide Burrito runners & the Hermitcrab server with some TLS configuration. By default, the Helm chart expects a secret named `burrito-hermitcrab-tls` to contain TLS configuration: `ca.crt`, `tls.crt`, and `tls.key`.
 
 ### Option 1: Use Cert-Manager
 
 The Helm chart is packaged with Cert-Manager configuration to use for Burrito/Hermitcrab TLS encryption.
-Assuming that Cert-Manager is installed on your cluster, set the `hermitcrab.tls.certmanager.use` parameter to `true`. This setting adds a Cert-Manager Certificate resource to be used with Burrito.  
+Assuming that Cert-Manager is installed on your cluster, set the `hermitcrab.tls.certmanager.use` parameter to `true`. This setting adds a Cert-Manager Certificate resource to be used with Burrito.
 Provide Certificate spec with the `hermitcrab.tls.certmanager.spec` value. You **must** set the `secretName` value to the same value specified in `config.burrito.hermitcrab.certificateSecretName` (default `burrito-hermitcrab-tls`)
 
 #### Example configuration with a self-signed issuer