feat: search, graphs, theme

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node-terminal",
+      "name": "Run Script: start",
+      "request": "launch",
+      "command": "pnpm run start",
+      "cwd": "${workspaceFolder}"
+    }
+  ]
+}

docs/infrastructure/01-Introduction.md

@@ -23,13 +23,12 @@ Why not a simple VM?
 AKS gives us the flexibility of a 10s pod deployment, reliability (with ArgoCD ensuring all pods are up and running all the time) and allows us to be more precise and clean in our infrastructure, with better monitoring and allocated resources for each application depending on the importance.  
 
 ## About this documentation
+
 :::important
 Most of the docs explain procedures with the Azure CLI and the Kubernetes CLI.  
-Make sure to [install and configure them](./Tutorials/setup#azure-cli--kubectl) to follow along.  
+Make sure to [install and configure them](./getting-started/setup#azure-cli--kubectl) to follow along.  
 Alternatively, you can see the [official Azure documentation](https://learn.microsoft.com/en-us/azure/?product=popular) for how to use the Azure portal.
 :::
 
-
-The best place to start is going through the [Tutorials](./Tutorials/setup) section to get a high level overview of how things are organized.  
+The best place to start is going through the [Getting Started](./getting-started/setup) section to get a high level overview of how things are organized.  
 If you're looking for a guide on how to achieve a specific outcome, you can look in the [Guides](./Guides/add-a-new-secret).
-

docs/infrastructure/02-getting-started/_category_.yml

@@ -0,0 +1,2 @@
+label: Getting Started
+position: 2

docs/infrastructure/02-getting-started/basic-knowledge/_category_.yml

@@ -0,0 +1,2 @@
+label: Basic Knowledge
+position: 2

docs/infrastructure/02-getting-started/basic-knowledge/index.md

@@ -0,0 +1,36 @@
+---
+title: Basic Knowledge
+---
+import DocCardList from '@theme/DocCardList';
+
+## Overview
+
+This section explains how we organized our infrastructure.
+
+Everything regarding the deployment of apps and services is divided into two repositories:
+
+- [polinetworkorg/terraform](https://github.com/polinetworkorg/terraform) - Contains the Terraform code to deploy the infrastructure. This defines the resources that are created on Azure, from specific things like KeyVaults, to the Kubernetes cluster itself.
+- [polinetworkorg/polinetwork-cd](https://github.com/polinetworkorg/polinetwork-cd) - Our GitOps repo, contains the manifests that define deployments specific for each app or service. This repository is connected to the ArgoCD instance running on the Kubernetes cluster.
+
+```mermaid
+flowchart TD
+  subgraph Github
+    tf([**terraform**])
+    cd([**polinetwork-cd**])
+  end
+  subgraph Azure
+    vm[VMs and other resources]
+    subgraph k8s[K8S cluster]
+      argocd[ArgoCD]
+      app@{ shape: processes, label: "Apps / Services" }
+    end
+  end
+
+  tf -.-> vm
+  tf -.-> k8s
+  vm <--> k8s
+  cd <-.-> argocd --> app
+```
+
+<!-- markdownlint-disable-next-line -->
+<DocCardList />

docs/infrastructure/02-Tutorials/pipelines/_category_.json → docs/infrastructure/02-getting-started/pipelines/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Pipelines",
-  "position": 3,
+  "position": 2,
   "link": {
     "type": "generated-index"
   }

docs/infrastructure/02-Tutorials/pipelines/ci.md → docs/infrastructure/02-getting-started/pipelines/ci.md

@@ -1,5 +1,8 @@
 ---
 sidebar_position: 1
+title: CI
 ---
-## Github Actions
-The first step of our CI processes is the Github Action workflow, in each repository. For example the [Bot Pipeline](https://github.com/PoliNetworkOrg/PoliNetworkBot_CSharp/blob/master/.github/workflows/ci-cd.yaml)
+
+## Continuous Integration
+
+The first step of our CI processes is the Github Action workflow, in each repository. For example the [Bot Pipeline](https://github.com/PoliNetworkOrg/PoliNetworkBot_CSharp/blob/master/.github/workflows/ci-cd.yaml)

docs/infrastructure/02-Tutorials/setup.md → docs/infrastructure/02-getting-started/setup.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 1
 ---
 # Setup
 

docs/infrastructure/03-Guides/add-a-new-secret.md

@@ -12,7 +12,6 @@ The following sections explain how to add a new secret.
 
 ## Basics
 
-
 There are three required steps:
 
 1. Add the secret into the "KV"
@@ -30,6 +29,7 @@ See [this section](#add-or-update-a-secret).
 ### Create the `SecretProviderClass`
 
 References:
+
 - [Microsoft Guide](https://learn.microsoft.com/en-us/azure/aks/csi-secrets-store-identity-access?tabs=azure-portal&pivots=access-with-a-user-assigned-managed-identity)
 - [Secrets Store CSI Driver](https://secrets-store-csi-driver.sigs.k8s.io)
 
@@ -43,12 +43,13 @@ kubectl get secretproviderclass --namespace <namespace>
 
 you should see a message like `No resources found in <namespace> namespace.`
 
-Otherwise the `SecretProviderClass` already exists and you can directly 
+Otherwise the `SecretProviderClass` already exists and you can directly
 [add a new secret](#add-kv-secrets-into-the-secretproviderclass).
 
 :::
 
 This is a basic `SecretProviderClass` manifest:
+
 ```yaml title="spc.yaml"
 apiVersion: secrets-store.csi.x-k8s.io/v1
 kind: SecretProviderClass
@@ -66,6 +67,7 @@ spec:
 ```
 
 A few things to note:
+
 - `usePodIdentity` should be set to `false` and `useVMManagedIdentity` should be set to `true` since we are using a VM managed identity.
 - `userAssignedIdentityID` should be set to the client ID of the managed identity we linked to the key vault.
 - `tenantId` should be set to the tenant ID of our Azure tenant.
@@ -87,13 +89,15 @@ az account show --query tenantId --output tsv
 ```sh
 az aks show --resource-group <resource-group> --name <cluster-name> --query addonProfiles.azureKeyvaultSecretsProvider.identity.clientId -o tsv
 ```
-`<resource-group>` and `<cluster-name>` can be found both in our [Terraform](https://github.com/PoliNetworkOrg/terraform/) or in the Azure Portal. 
+
+`<resource-group>` and `<cluster-name>` can be found both in our [Terraform](https://github.com/PoliNetworkOrg/terraform/) or in the Azure Portal.
 
 :::
 
 ### Add "KV" secrets into the `SecretProviderClass`
 
 Inside the `SecretProviderClass` manifest, add "KV" secrets:
+
 ```yaml title="spc.yaml"
 apiVersion: secrets-store.csi.x-k8s.io/v1
 kind: SecretProviderClass
@@ -120,7 +124,7 @@ spec:
     # add-highlight-end
 ```
 
-In this example, we map two secrets (`<secret-1-key>` and `<secret-2-key>`) 
+In this example, we map two secrets (`<secret-1-key>` and `<secret-2-key>`)
 from the key vault `kv-polinetwork` to a volume you can mount in your pod.  
 
 ### Mount the secret volume inside the pod
@@ -163,7 +167,7 @@ spec:
         readOnly: true
         volumeAttributes:
           secretProviderClass: '<namespace>-spc' # The name of the SecretProviderClass
-#add-highlight-end
+# add-highlight-end
 ```
 
 After applying this manifest to the cluster, you can retrieve the secret by reading the files in the `/mnt/secrets-store/` directory (`mountPath` parameter).  
@@ -188,7 +192,7 @@ In the [previous section](#add-kv-secrets-into-the-secretproviderclass), we have
 ## Loading the secret inside an Environment Variable
 
 :::important
-Even if you want to load the secret as an ENV variable, it's **REQUIRED** to follow every steps in the previous section, including 
+Even if you want to load the secret as an ENV variable, it's **REQUIRED** to follow every steps in the previous section, including
 [mounting the secret volume](#mount-the-secret-volume-inside-the-pod).
 
 You can find more about why this is the case [here](https://github.com/kubernetes-sigs/secrets-store-csi-driver/issues/813)
@@ -197,7 +201,8 @@ You can find more about why this is the case [here](https://github.com/kubernete
 To load the secret as an Environment Variable follows the following steps.
 
 ### Register the secret as a k8s secret
-Inside the `ServiceProviderClass` manifest, add a new field `secretObjects` to create a 
+
+Inside the `ServiceProviderClass` manifest, add a new field `secretObjects` to create a
 new k8s secret collection:
 
 ```yaml title="spc.yaml"
@@ -235,9 +240,9 @@ spec:
           objectType: secret
 ```
 
-
 ### Use the secret as environment variable
-After [mounting the secret volume](#mount-the-secret-volume-inside-the-pod) and [configuring the k8s secret](#register-the-secret-as-a-k8s-secret), 
+
+After [mounting the secret volume](#mount-the-secret-volume-inside-the-pod) and [configuring the k8s secret](#register-the-secret-as-a-k8s-secret),
 you can add an environment variable with the secret as value reference:
 
 ```yaml title="my-spc-example-pod.yaml"
@@ -283,40 +288,50 @@ spec:
 ```
 
 ## "KV" management
+
 ### Add or update a secret
+
 You can add (or update) a secret with the following command:
+
 ```sh
 az keyvault secret set --vault-name "kv-polinetwork" --name "<secret-name>" --value "<secret-value>"
 ```
 
 :::tip
 If the secret value is too long or you don't want to copy/paste in terminal you can use a file instead.
+
 1. Paste the secret value into a text file (no extension or ".txt" is valid) on a **single line**
 2. Run the following command
+
    ```sh
    az keyvault secret set --vault-name "kv-polinetwork" --name "<secret-name>" --file "<filename>"
    ```
+
 :::
 
 ### Delete a secret
+
 You can delete a secret with the following command:
+
 ```sh
 az keyvault secret delete --vault-name "kv-polinetwork" --name "<secret-name>"
 ```
 
 After the deletion, the secret remains in a `Recoverable State` for 7 days.  
 During this period the secret can be recovered with the following command:
+
 ```sh
 az keyvault secret recover --vault-name "kv-polinetwork" --name "<secret-name>"
 ```
 
 To **permanently delete** that secret, after 7 days from deletion you can run the following command:
+
 ```sh
 az keyvault secret purge --vault-name "kv-polinetwork" --name "<secret-name>"
 ```
 
 :::note
-To **update/re-set** that secret, during the 7 days retention period, you must recover it first, 
+To **update/re-set** that secret, during the 7 days retention period, you must recover it first,
 then run the command to update it
 
 If you try to `set` a secret that has been deleted within the last 7 days without restoring it first, you get the following error:
@@ -331,10 +346,11 @@ Inner error: {
 }
 #error-highlight-end
 ```
-:::
 
+:::
 
 ## Examples
+
 In this section you can find working examples.  
 It is recommended to read the ["Basics" section](#basics) to understand how it works.
 
@@ -343,7 +359,8 @@ You still need to set `tenantId`, `userAssignedIdentityID` and secret keys to ma
 :::
 
 ### Minimal
-```yaml title="test-secret/spc.yaml"
+
+```yaml title="test-secret/spc.yaml" showLineNumbers
 apiVersion: secrets-store.csi.x-k8s.io/v1
 kind: SecretProviderClass
 metadata:
@@ -367,7 +384,7 @@ spec:
           objectType: secret
 ```
 
-```yaml title="test-secret/example-pod.yaml"
+```yaml title="test-secret/example-pod.yaml" showLineNumbers
 kind: Pod
 apiVersion: v1
 metadata:
@@ -403,7 +420,7 @@ spec:
 
 ### Environment Variable
 
-```yaml title="test-secret-env/spc.yaml"
+```yaml title="test-secret-env/spc.yaml" showLineNumbers
 apiVersion: secrets-store.csi.x-k8s.io/v1
 kind: SecretProviderClass
 metadata:
@@ -430,7 +447,7 @@ spec:
           objectType: secret
 ```
 
-```yaml title="test-secret-env/example-pod.yaml"
+```yaml title="test-secret-env/example-pod.yaml" showLineNumbers
 kind: Pod
 apiVersion: v1
 metadata:
@@ -469,4 +486,3 @@ spec:
         volumeAttributes:
           secretProviderClass: 'test-secret-env-spc'
 ```
-

docusaurus.config.ts

@@ -1,4 +1,4 @@
-import { themes as prismThemes } from 'prism-react-renderer'
+import materialThemes from './themes/material'
 import type { Config } from '@docusaurus/types'
 import type * as Preset from '@docusaurus/preset-classic'
 
@@ -52,6 +52,11 @@ const config: Config = {
     ],
   ],
 
+  themes: [
+    [require.resolve('@easyops-cn/docusaurus-search-local'), { hashed: true }],
+    '@docusaurus/theme-mermaid',
+  ],
+
   themeConfig: {
     // Replace with your project's social card
     image: 'img/docusaurus-social-card.jpg',
@@ -140,33 +145,41 @@ const config: Config = {
         height: '100px',
       },
     },
+
     prism: {
-      theme: prismThemes.github,
-      darkTheme: prismThemes.dracula,
+      theme: materialThemes.darker,
+      darkTheme: materialThemes.darker,
       magicComments: [
         {
           className: 'theme-code-block-highlighted-line',
           line: 'highlight-next-line',
-          block: {start: 'highlight-start', end: 'highlight-end'},
+          block: { start: 'highlight-start', end: 'highlight-end' },
         },
         {
           className: 'code-block-add-line',
           line: 'add-highlight-next-line',
-          block: {start: 'add-highlight-start', end: 'add-highlight-end'},
+          block: { start: 'add-highlight-start', end: 'add-highlight-end' },
         },
         {
           className: 'code-block-remove-line',
           line: 'remove-highlight-next-line',
-          block: {start: 'remove-highlight-start', end: 'remove-highlight-end'},
+          block: {
+            start: 'remove-highlight-start',
+            end: 'remove-highlight-end',
+          },
         },
         {
           className: 'code-block-error-line',
           line: 'error-highlight-next-line',
-          block: {start: 'error-highlight-start', end: 'error-highlight-end'},
+          block: { start: 'error-highlight-start', end: 'error-highlight-end' },
         },
-      ]
+      ],
     },
   } satisfies Preset.ThemeConfig,
+
+  markdown: {
+    mermaid: true,
+  },
 }
 
 export default config