diff --git a/docs/index.md b/docs/index.md
index 888c329..5e759b8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -11,7 +11,7 @@ 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)
+## Homebrew (macOS) (recommended)
 
 If you are using macOS and have [Homebrew](https://brew.sh/) installed, you can
 install `datumctl` via our official tap:
@@ -27,35 +27,7 @@ brew install datumctl
 brew upgrade datumctl
 ```
 
-## nix (Linux and macOS)
-
-datumctl ships with a `flake.nix` so you don't have to install anything:
-
-```
-# Pick latest from git
-nix run github:datum-cloud/datumctl
-
-# Specify version
-nix run github:datum-cloud/datumctl/b044455d877b800812e4fd78e42429c1617c011b
-
-# Run from local git clone
-nix run
-
-# Start shell with all dependencies available
-nix develop --command zsh
-
-# Build locally
-nix build
-
-# ...or for specific platform
-nix build .#packages.x86_64-linux.default
-nix build .#packages.aarch64-linux.default
-```
-
-You can, however, incorporate it into your home-manager build or other
-flake so that it's always available in your profile.
-
-## Pre-built binaries (recommended)
+## Pre-built binaries
 
 The easiest way to install `datumctl` is by downloading the pre-built binary
 for your operating system and architecture from the
@@ -94,6 +66,35 @@ sudo mv datumctl /usr/local/bin/
 > The `sudo mv` command might require administrator privileges. Adjust the
 > destination path `/usr/local/bin/` if needed for your system.
 
+## nix (Linux and macOS)
+
+datumctl ships with a `flake.nix` so you don't have to install anything:
+
+```
+# Pick latest from git
+nix run github:datum-cloud/datumctl
+
+# Specify version
+nix run github:datum-cloud/datumctl/b044455d877b800812e4fd78e42429c1617c011b
+
+# Run from local git clone
+nix run
+
+# Start shell with all dependencies available
+nix develop --command zsh
+
+# Build locally
+nix build
+
+# ...or for specific platform
+nix build .#packages.x86_64-linux.default
+nix build .#packages.aarch64-linux.default
+```
+
+You can, however, incorporate it into your home-manager build or other
+flake so that it's always available in your profile.
+
+
 ## Building from source
 
 If you prefer, you can build `datumctl` from source:
diff --git a/go.sum b/go.sum
index f62a67d..993af73 100644
--- a/go.sum
+++ b/go.sum
@@ -222,8 +222,6 @@ golang.org/x/mod v0.31.0 h1:HaW9xtz0+kOcWKwli0ZXy79Ix+UW/vOfmWI5QVd2tgI=
 golang.org/x/mod v0.31.0/go.mod h1:43JraMp9cGx1Rx3AqioxrbrhNsLl2l/iNAvuBkrezpg=
 golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
 golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
-golang.org/x/oauth2 v0.34.0 h1:hqK/t4AKgbqWkdkcAeI8XLmbK+4m4G5YeQRrmiotGlw=
-golang.org/x/oauth2 v0.34.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
 golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
diff --git a/internal/cmd/docs/generate-cli-documentation.go b/internal/cmd/docs/generate-cli-documentation.go
index 827c9aa..e3ddc01 100644
--- a/internal/cmd/docs/generate-cli-documentation.go
+++ b/internal/cmd/docs/generate-cli-documentation.go
@@ -34,6 +34,8 @@ func GenerateDocumentationCmd(root *cobra.Command) *cobra.Command {
 	)
 	const fmTemplate = `---
 title: "%s"
+sidebar:
+  hidden: true
 ---
 `
 
@@ -44,7 +46,7 @@ title: "%s"
 	}
 	linkHandler := func(name string) string {
 		base := strings.TrimSuffix(name, path.Ext(name))
-		return "/docs/datumctl/commands/" + strings.ToLower(base) + "/"
+		return "/docs/datumctl/command/" + strings.ToLower(base) + "/"
 	}
 	cmd := &cobra.Command{
 		Use:     "generate-cli-docs",
@@ -75,6 +77,7 @@ func downscaleMarkdownHeadersInDir(root string) error {
 }
 
 func downscaleMarkdownHeadersInFile(filename string) error {
+	isDatumctlDoc := filepath.Base(filename) == "datumctl.md"
 	in, err := os.Open(filename)
 	if err != nil {
 		return err
@@ -94,6 +97,7 @@ func downscaleMarkdownHeadersInFile(filename string) error {
 	writer := bufio.NewWriter(tmp)
 	inFence := false
 	var fenceMarker string
+	dropNextH2Header := true
 
 	for {
 		line, err := reader.ReadString('\n')
@@ -114,8 +118,23 @@ func downscaleMarkdownHeadersInFile(filename string) error {
 				fenceMarker = ""
 			}
 		} else if !inFence {
+			if isDatumctlDoc {
+				line = replaceDatumctlTitle(line)
+			}
+			if dropNextH2Header {
+				var dropped bool
+				line, dropped = dropFirstH2HeaderLine(line)
+				if dropped {
+					dropNextH2Header = false
+					if isEOF {
+						break
+					}
+					continue
+				}
+			}
 			line = replaceH1WithH3(line)
 			line = normalizeSeeAlsoLine(line)
+			line = normalizeDatumctlCommandLinks(line)
 		}
 
 		if _, werr := writer.WriteString(line); werr != nil {
@@ -139,6 +158,14 @@ func downscaleMarkdownHeadersInFile(filename string) error {
 	return os.Rename(tmp.Name(), filename)
 }
 
+func dropFirstH2HeaderLine(line string) (string, bool) {
+	trimmed := strings.TrimLeft(line, " \t")
+	if strings.HasPrefix(trimmed, "## ") {
+		return "", true
+	}
+	return line, false
+}
+
 func replaceH1WithH3(line string) string {
 	trimmed := strings.TrimLeft(line, " \t")
 	if len(trimmed) == 0 || trimmed[0] != '#' {
@@ -171,3 +198,18 @@ func normalizeSeeAlsoLine(line string) string {
 	}
 	return line
 }
+
+func normalizeDatumctlCommandLinks(line string) string {
+	return strings.ReplaceAll(line, "/docs/datumctl/command/datumctl/", "/docs/datumctl/cli-reference/")
+}
+
+func replaceDatumctlTitle(line string) string {
+	trimmed := strings.TrimSpace(line)
+	if trimmed == "hidden: true" {
+		return strings.Replace(line, "hidden: true", "hidden: false", 1)
+	}
+	if trimmed == `title: "datumctl"` {
+		return strings.Replace(line, `title: "datumctl"`, `title: "CLI command reference"`, 1)
+	}
+	return line
+}
diff --git a/internal/cmd/docs/generate-cli-documentation_test.go b/internal/cmd/docs/generate-cli-documentation_test.go
index 1c28606..30b5005 100644
--- a/internal/cmd/docs/generate-cli-documentation_test.go
+++ b/internal/cmd/docs/generate-cli-documentation_test.go
@@ -58,6 +58,33 @@ func TestNormalizeSeeAlsoLine(t *testing.T) {
 	}
 }
 
+func TestDropFirstH2HeaderLine(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		in      string
+		want    string
+		dropped bool
+	}{
+		{name: "h2 header dropped", in: "## Title\n", want: "", dropped: true},
+		{name: "h2 with indent dropped", in: "  ## Title\n", want: "", dropped: true},
+		{name: "h3 not dropped", in: "### Title\n", want: "### Title\n", dropped: false},
+		{name: "non-header", in: "Title\n", want: "Title\n", dropped: false},
+	}
+
+	for _, test := range tests {
+		test := test
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			got, dropped := dropFirstH2HeaderLine(test.in)
+			if got != test.want || dropped != test.dropped {
+				t.Fatalf("dropFirstH2HeaderLine(%q) = (%q, %v), want (%q, %v)", test.in, got, dropped, test.want, test.dropped)
+			}
+		})
+	}
+}
+
 func TestDownscaleMarkdownHeadersInFile_RespectsFences(t *testing.T) {
 	t.Parallel()
 
@@ -93,7 +120,6 @@ func TestDownscaleMarkdownHeadersInFile_RespectsFences(t *testing.T) {
 		"```bash\n" +
 		"# Not\n" +
 		"```\n" +
-		"## B\n" +
 		"~~~\n" +
 		"### Not2\n" +
 		"~~~\n"