Merge pull request #94 from datum-cloud/feat/make-docs-datum-net-compliant

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

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   swells@datum.net               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 == "swells@datum.net" && objectRef.apiGroup == "networking.datumapis.com"'
 TIMESTAMP             VERB   USER               NAMESPACE   RESOURCE   NAME        STATUS
 2026-01-14 10:08:33   get    swells@datum.net   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 == "swells@datum.net" && objectRef.apiGroup == "networking.datumapis.com"' --limit 3
 TIMESTAMP             VERB   USER               NAMESPACE   RESOURCE   NAME        STATUS
 2026-01-14 10:08:33   get    swells@datum.net   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
 ```