chore: format docs in a way that will make datum.net happy

Since we want datum.net to correctly render our documentation we need to
keep it compliant with their syntax.

In practice it means adding the right metadata to our markdown file and
remove some code highlighting that is not supported yet for datum.net

Author: gianarb

docs/README.md

@@ -1,3 +1,9 @@
+---
+title: "Activity"
+sidebar:
+  order: 3
+---
+
 # Activity
 
 The `datumctl activity` command is available for interacting with the [activity
@@ -8,7 +14,7 @@ with the platform.
 You can see the full list of commands and CLI options by using the `--help`
 flag.
 
-```shell
+```
 $ datumctl activity --help
 ```
 
@@ -28,7 +34,7 @@ logs to understand what's happening within your organization and projects.
 Use the `--project` and `--organization` flag to control which context audit
 logs are retrieved from.
 
-```shell
+```
 $ datumctl activity query --project datum-cloud
 TIMESTAMP             VERB     USER               NAMESPACE   RESOURCE          NAME       STATUS
 2026-01-14 09:52:43   create   [email protected]               auditlogqueries              201
@@ -43,7 +49,7 @@ The `--filter` command is available to filter the audit logs returned in the
 query. The filter option accepts a [CEL expression][cel] to select which audit
 logs should be returned.
 
-```shell
+```
 $ datumctl activity query --project datum-cloud --limit 10 --filter='user.username == "[email protected]" && objectRef.apiGroup == "networking.datumapis.com"'
 TIMESTAMP             VERB   USER               NAMESPACE   RESOURCE   NAME        STATUS
 2026-01-14 10:08:33   get    [email protected]   default     domains    datum.net   200
@@ -62,7 +68,7 @@ The `--continue` option is available to paginate requests when additional
 results are available. The CLI will provide the continue option to use for the
 next page of requests.
 
-```shell
+```
 $ datumctl activity query --project datum-cloud --limit 10 --filter='user.username == "[email protected]" && objectRef.apiGroup == "networking.datumapis.com"' --limit 3
 TIMESTAMP             VERB   USER               NAMESPACE   RESOURCE   NAME        STATUS
 2026-01-14 10:08:33   get    [email protected]   default     domains    datum.net   200
@@ -83,7 +89,7 @@ that are helpful to users to understand the activity. You can also output the
 results as `yaml` or `json` to see the full audit logs that were retrieved by
 the query.
 
-```shell
+```
 $ datumctl activity query --project datum-cloud -o yaml
 apiVersion: audit.k8s.io/v1
 items:

docs/user/commands/activity.md docs/activity.mddocs/user/commands/activity.md renamed to docs/activity.md

@@ -1,4 +1,8 @@
-# Authentication
+---
+title: "Authentication"
+sidebar:
+  order: 2
+---
 
 `datumctl` uses OAuth 2.0 and OpenID Connect (OIDC) with the PKCE extension for
 secure authentication against Datum Cloud. This avoids the need to handle static
@@ -20,7 +24,7 @@ keyring.
 
 To authenticate with Datum Cloud, use the `login` command:
 
-```bash
+```
 datumctl auth login [--hostname <auth-hostname>] [-v]
 ```
 
@@ -49,7 +53,7 @@ Once logged in, you typically need to configure `kubectl` to authenticate to
 Datum Cloud Kubernetes clusters using your `datumctl` login session. Use the
 `update-kubeconfig` command:
 
-```bash
+```
 datumctl auth update-kubeconfig [--kubeconfig <path>] [--project <name>] [--organization <name>]
 ```
 
@@ -75,7 +79,7 @@ automatically use your active `datumctl` login session for authentication.
 
 To see which users you have authenticated locally, use the `list` command:
 
-```bash
+```
 datumctl auth list
 # Alias: datumctl auth ls
 ```
@@ -91,7 +95,7 @@ If you have logged in with multiple user accounts (visible via
 `datumctl auth list`), you can switch which account is active using the
 `switch` command:
 
-```bash
+```
 datumctl auth switch <user-email>
 ```
 
@@ -108,7 +112,7 @@ To remove stored credentials, use the `logout` command.
 
 **Log out a specific user:**
 
-```bash
+```
 datumctl auth logout <user-email>
 ```
 
@@ -117,7 +121,7 @@ Replace `<user-email>` with the email address shown in the
 
 **Log out all users:**
 
-```bash
+```
 datumctl auth logout --all
 ```
 
@@ -129,7 +133,7 @@ The `get-token` command retrieves the current access token for the *active*
 authenticated user. This is primarily used internally by other tools (like
 `kubectl`) but can be used directly if needed.
 
-```bash
+```
 datumctl auth get-token [-o <format>]
 ```
 

docs/user/authentication.md docs/authentication.mddocs/user/authentication.md renamed to docs/authentication.md

@@ -1,4 +1,8 @@
-# Authentication flow
+---
+title: "Authentication flow"
+sidebar:
+  order: 7
+---
 
 `datumctl` utilizes OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for
 Code Exchange) for user authentication. This flow is orchestrated by the

docs/developer/README.md

@@ -1,4 +1,8 @@
-# Code structure
+---
+title: "Code structure"
+sidebar:
+  order: 6
+---
 
 The `datumctl` codebase is organized primarily within the `internal` directory,
 following common Go practices.

docs/developer/authentication_flow.md

@@ -1,4 +1,8 @@
-# Developer overview
+---
+title: "Overview"
+sidebar:
+  order: 5
+---
 
 `datumctl` is the command-line interface for interacting with Datum Cloud. It is
 built using Go and the [Cobra](https://cobra.dev/) library for CLI structure.

docs/developer/code_structure.md

@@ -1,3 +1,6 @@
+---
+title: "Releases"
+---
 # Releases
 
 This guide explains how to cut a `datumctl` release locally with GoReleaser and

docs/developer/overview.md

@@ -1,13 +1,22 @@
-# Installation
+---
+title: "Installation"
+sidebar:
+  order: 1
+---
 
-This section describes how to install `datumctl`.
+Welcome to the documentation for `datumctl`, the command-line interface for
+interacting with Datum Cloud.
+
+Let's start installing the binary itself, but if you want to get deeper, make a
+contribution or you are a curious developer nativate to the [documentation we
+wrote specifically for you.](developer/overview)
 
 ## Homebrew (macOS)
 
 If you are using macOS and have [Homebrew](https://brew.sh/) installed, you can
 install `datumctl` via our official tap:
 
-```bash
+```
 # Tap the Datum Cloud formula repository (only needs to be done once)
 brew tap datum-cloud/homebrew-tap
 
@@ -74,7 +83,7 @@ This example shows how to download and install a specific version. You **must**:
     architecture found on the releases page (e.g.,
     `datumctl_Darwin_arm64.tar.gz`).
 
-```bash
+```
 VERSION="<version>"
 ARCHIVE="<archive_filename>"
 curl -sSL "https://github.com/datum-cloud/datumctl/releases/download/${VERSION}/${ARCHIVE}" | tar xz
@@ -93,12 +102,12 @@ If you prefer, you can build `datumctl` from source:
     *   Go (version 1.21 or later)
     *   Git
 2.  **Clone the repository:**
-    ```bash
+    ```
     git clone https://github.com/datum-cloud/datumctl.git
     cd datumctl
     ```
 3.  **Build the binary:**
-    ```bash
+    ```
     go build -o datumctl .
     ```
 4.  **Install:** Move the resulting `datumctl` binary to a directory in your
@@ -108,7 +117,7 @@ If you prefer, you can build `datumctl` from source:
 
 To verify the installation, run:
 
-```bash
+```
 datumctl version
 ```