Skip to content

Commit ebd0174

Browse files
mattappersonmattapperson
authored
docs: use flat navigation.pages for multi-repo sourceRef (#386)
1 parent 28299a7 commit ebd0174

2 files changed

Lines changed: 49 additions & 66 deletions

File tree

‎docs/docs.json‎

Lines changed: 29 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -8,45 +8,35 @@
88
"dark": "#6467f2"
99
},
1010
"navigation": {
11-
"groups": [
12-
{
13-
"group": "Getting Started",
14-
"pages": [
15-
"overview"
16-
]
17-
},
18-
{
19-
"group": "API Reference",
20-
"pages": [
21-
"sdks/analytics/README",
22-
"sdks/apikeys/README",
23-
"sdks/benchmarks/README",
24-
"sdks/betaanalytics/README",
25-
"sdks/byok/README",
26-
"sdks/chat/README",
27-
"sdks/classifications/README",
28-
"sdks/credits/README",
29-
"sdks/datasets/README",
30-
"sdks/embeddings/README",
31-
"sdks/endpoints/README",
32-
"sdks/files/README",
33-
"sdks/generations/README",
34-
"sdks/guardrails/README",
35-
"sdks/images/README",
36-
"sdks/models/README",
37-
"sdks/oauth/README",
38-
"sdks/observability/README",
39-
"sdks/organization/README",
40-
"sdks/presets/README",
41-
"sdks/providers/README",
42-
"sdks/rerank/README",
43-
"sdks/responses/README",
44-
"sdks/stt/README",
45-
"sdks/tts/README",
46-
"sdks/videogeneration/README",
47-
"sdks/workspaces/README"
48-
]
49-
}
11+
"pages": [
12+
"overview",
13+
"sdks/analytics/README",
14+
"sdks/apikeys/README",
15+
"sdks/benchmarks/README",
16+
"sdks/betaanalytics/README",
17+
"sdks/byok/README",
18+
"sdks/chat/README",
19+
"sdks/classifications/README",
20+
"sdks/credits/README",
21+
"sdks/datasets/README",
22+
"sdks/embeddings/README",
23+
"sdks/endpoints/README",
24+
"sdks/files/README",
25+
"sdks/generations/README",
26+
"sdks/guardrails/README",
27+
"sdks/images/README",
28+
"sdks/models/README",
29+
"sdks/oauth/README",
30+
"sdks/observability/README",
31+
"sdks/organization/README",
32+
"sdks/presets/README",
33+
"sdks/providers/README",
34+
"sdks/rerank/README",
35+
"sdks/responses/README",
36+
"sdks/stt/README",
37+
"sdks/tts/README",
38+
"sdks/videogeneration/README",
39+
"sdks/workspaces/README"
5040
]
5141
}
5242
}

‎scripts/gen-docs-nav.sh‎

Lines changed: 20 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,16 @@
11
#!/usr/bin/env bash
2-
# Regenerate the "API Reference" navigation group in docs/docs.json from the
3-
# service pages Speakeasy emits under docs/sdks/<tag>/README.mdx.
2+
# Regenerate docs/docs.json navigation from the service pages Speakeasy emits
3+
# under docs/sdks/<tag>/README.mdx.
44
#
5-
# Run this after `speakeasy run` so new API sections appear in the sidebar
6-
# without hand-editing docs.json. Only the "API Reference" group's `pages`
7-
# array is rewritten; every other part of docs.json is preserved untouched.
8-
# Pages are listed alphabetically by tag. Idempotent: running with no doc
9-
# changes leaves docs.json byte-identical.
5+
# The docs.json exposes a flat `navigation.pages` array so it can be mounted
6+
# into the base docs site via a `sourceRef` inside a `pages` context (Mintlify
7+
# requires the referenced source to define the same navigation type as the slot
8+
# it is mounted into). The array is: the "overview" page first, then every
9+
# service page sorted alphabetically by tag.
10+
#
11+
# Run after `speakeasy run` so new API sections appear without hand-editing
12+
# docs.json. Only `navigation.pages` is rewritten; $schema/theme/name/colors
13+
# are preserved. Idempotent: no doc changes -> byte-identical output.
1014
#
1115
# Requires: bash, jq. No network, no toolchain.
1216
set -euo pipefail
@@ -15,46 +19,35 @@ ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
1519
cd "$ROOT"
1620

1721
DOCS_JSON="docs/docs.json"
18-
GROUP="API Reference"
22+
OVERVIEW="overview"
1923

2024
if [[ ! -f "$DOCS_JSON" ]]; then
2125
echo "missing $DOCS_JSON" >&2
2226
exit 1
2327
fi
2428

25-
# Collect service page paths (docs.json paths are repo-doc-root-relative and
26-
# carry no extension), sorted alphabetically by tag.
29+
# Collect service page paths (docs.json paths are doc-root-relative, no
30+
# extension), sorted alphabetically by tag.
2731
pages=()
32+
# Lead with the overview landing page when present.
33+
[[ -f "docs/${OVERVIEW}.mdx" ]] && pages+=("$OVERVIEW")
2834
while IFS= read -r readme; do
2935
# docs/sdks/<tag>/README.mdx -> sdks/<tag>/README
3036
rel="${readme#docs/}"
3137
pages+=("${rel%.mdx}")
3238
done < <(find docs/sdks -mindepth 2 -maxdepth 2 -name 'README.mdx' | sort)
3339

3440
if ((${#pages[@]} == 0)); then
35-
echo "no service pages found under docs/sdks/*/README.mdx" >&2
41+
echo "no pages found (missing docs/${OVERVIEW}.mdx and docs/sdks/*/README.mdx)" >&2
3642
exit 1
3743
fi
3844

39-
# Build a JSON array of the page paths.
4045
pages_json="$(printf '%s\n' "${pages[@]}" | jq -R . | jq -s .)"
4146

42-
# Rewrite only the matching group's pages. Fail loudly if the group is absent
43-
# so a renamed/missing group never silently produces an empty sidebar.
4447
tmp="$(mktemp)"
45-
jq --indent 2 \
46-
--arg group "$GROUP" \
47-
--argjson pages "$pages_json" '
48-
(.navigation.groups
49-
| map(select(.group == $group))
50-
| length) as $matches
51-
| if $matches == 0 then
52-
error("group \"" + $group + "\" not found in navigation.groups")
53-
else . end
54-
| .navigation.groups |= map(
55-
if .group == $group then .pages = $pages else . end
56-
)
48+
jq --indent 2 --argjson pages "$pages_json" '
49+
.navigation = {pages: $pages}
5750
' "$DOCS_JSON" >"$tmp"
5851

5952
mv "$tmp" "$DOCS_JSON"
60-
echo "updated $DOCS_JSON: ${#pages[@]} pages in \"$GROUP\""
53+
echo "updated $DOCS_JSON: ${#pages[@]} pages in navigation.pages"

0 commit comments

Comments
 (0)