docs: use flat navigation.pages for multi-repo sourceRef

docs/docs.json

@@ -8,45 +8,35 @@
     "dark": "#6467f2"
   },
   "navigation": {
-    "groups": [
-      {
-        "group": "Getting Started",
-        "pages": [
-          "overview"
-        ]
-      },
-      {
-        "group": "API Reference",
-        "pages": [
-          "sdks/analytics/README",
-          "sdks/apikeys/README",
-          "sdks/benchmarks/README",
-          "sdks/betaanalytics/README",
-          "sdks/byok/README",
-          "sdks/chat/README",
-          "sdks/classifications/README",
-          "sdks/credits/README",
-          "sdks/datasets/README",
-          "sdks/embeddings/README",
-          "sdks/endpoints/README",
-          "sdks/files/README",
-          "sdks/generations/README",
-          "sdks/guardrails/README",
-          "sdks/images/README",
-          "sdks/models/README",
-          "sdks/oauth/README",
-          "sdks/observability/README",
-          "sdks/organization/README",
-          "sdks/presets/README",
-          "sdks/providers/README",
-          "sdks/rerank/README",
-          "sdks/responses/README",
-          "sdks/stt/README",
-          "sdks/tts/README",
-          "sdks/videogeneration/README",
-          "sdks/workspaces/README"
-        ]
-      }
+    "pages": [
+      "overview",
+      "sdks/analytics/README",
+      "sdks/apikeys/README",
+      "sdks/benchmarks/README",
+      "sdks/betaanalytics/README",
+      "sdks/byok/README",
+      "sdks/chat/README",
+      "sdks/classifications/README",
+      "sdks/credits/README",
+      "sdks/datasets/README",
+      "sdks/embeddings/README",
+      "sdks/endpoints/README",
+      "sdks/files/README",
+      "sdks/generations/README",
+      "sdks/guardrails/README",
+      "sdks/images/README",
+      "sdks/models/README",
+      "sdks/oauth/README",
+      "sdks/observability/README",
+      "sdks/organization/README",
+      "sdks/presets/README",
+      "sdks/providers/README",
+      "sdks/rerank/README",
+      "sdks/responses/README",
+      "sdks/stt/README",
+      "sdks/tts/README",
+      "sdks/videogeneration/README",
+      "sdks/workspaces/README"
     ]
   }
 }

scripts/gen-docs-nav.sh

@@ -1,12 +1,16 @@
 #!/usr/bin/env bash
-# Regenerate the "API Reference" navigation group in docs/docs.json from the
-# service pages Speakeasy emits under docs/sdks/<tag>/README.mdx.
+# Regenerate docs/docs.json navigation from the service pages Speakeasy emits
+# under docs/sdks/<tag>/README.mdx.
 #
-# Run this after `speakeasy run` so new API sections appear in the sidebar
-# without hand-editing docs.json. Only the "API Reference" group's `pages`
-# array is rewritten; every other part of docs.json is preserved untouched.
-# Pages are listed alphabetically by tag. Idempotent: running with no doc
-# changes leaves docs.json byte-identical.
+# The docs.json exposes a flat `navigation.pages` array so it can be mounted
+# into the base docs site via a `sourceRef` inside a `pages` context (Mintlify
+# requires the referenced source to define the same navigation type as the slot
+# it is mounted into). The array is: the "overview" page first, then every
+# service page sorted alphabetically by tag.
+#
+# Run after `speakeasy run` so new API sections appear without hand-editing
+# docs.json. Only `navigation.pages` is rewritten; $schema/theme/name/colors
+# are preserved. Idempotent: no doc changes -> byte-identical output.
 #
 # Requires: bash, jq. No network, no toolchain.
 set -euo pipefail
@@ -15,46 +19,35 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$ROOT"
 
 DOCS_JSON="docs/docs.json"
-GROUP="API Reference"
+OVERVIEW="overview"
 
 if [[ ! -f "$DOCS_JSON" ]]; then
 	echo "missing $DOCS_JSON" >&2
 	exit 1
 fi
 
-# Collect service page paths (docs.json paths are repo-doc-root-relative and
-# carry no extension), sorted alphabetically by tag.
+# Collect service page paths (docs.json paths are doc-root-relative, no
+# extension), sorted alphabetically by tag.
 pages=()
+# Lead with the overview landing page when present.
+[[ -f "docs/${OVERVIEW}.mdx" ]] && pages+=("$OVERVIEW")
 while IFS= read -r readme; do
 	# docs/sdks/<tag>/README.mdx -> sdks/<tag>/README
 	rel="${readme#docs/}"
 	pages+=("${rel%.mdx}")
 done < <(find docs/sdks -mindepth 2 -maxdepth 2 -name 'README.mdx' | sort)
 
 if ((${#pages[@]} == 0)); then
-	echo "no service pages found under docs/sdks/*/README.mdx" >&2
+	echo "no pages found (missing docs/${OVERVIEW}.mdx and docs/sdks/*/README.mdx)" >&2
 	exit 1
 fi
 
-# Build a JSON array of the page paths.
 pages_json="$(printf '%s\n' "${pages[@]}" | jq -R . | jq -s .)"
 
-# Rewrite only the matching group's pages. Fail loudly if the group is absent
-# so a renamed/missing group never silently produces an empty sidebar.
 tmp="$(mktemp)"
-jq --indent 2 \
-	--arg group "$GROUP" \
-	--argjson pages "$pages_json" '
-	(.navigation.groups
-		| map(select(.group == $group))
-		| length) as $matches
-	| if $matches == 0 then
-		error("group \"" + $group + "\" not found in navigation.groups")
-	  else . end
-	| .navigation.groups |= map(
-		if .group == $group then .pages = $pages else . end
-	  )
+jq --indent 2 --argjson pages "$pages_json" '
+	.navigation = {pages: $pages}
 ' "$DOCS_JSON" >"$tmp"
 
 mv "$tmp" "$DOCS_JSON"
-echo "updated $DOCS_JSON: ${#pages[@]} pages in \"$GROUP\""
+echo "updated $DOCS_JSON: ${#pages[@]} pages in navigation.pages"