docs: use flat navigation.pages for multi-repo sourceRef (#386)

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,16 +19,18 @@ 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/}"
@@ -32,29 +38,16 @@ while IFS= read -r readme; do
 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"