docs: update docs + docs CI (#505)

Author: corrieriluca

.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