Sync kb-nav script with CoreWeave

[dfinster]

Summary

Syncs the Knowledgebase Nav generator (scripts/knowledgebase-nav/) with the CoreWeave-aligned utility: Mintlify root and badge styling come from config.yaml, the --repo-root CLI is removed, and docs/tests are updated so the tool reads as a reusable Mintlify docs utility rather than a hard-coded wandb-docs-only layout.

Motivation / context

We are planning to unify this utility with the CoreWeave version as part of the Q2 DocEngine plans. This unites the script across those two repos, with the only difference being the config.yaml file in each. Future updates can stay in sync, or be pulled from DocEngine.

• Support navigation generation should work when the Mintlify site root is the repo root or a subdirectory (for example public-docs).
• Badge color should be configurable instead of hard-coded orange.
• PR reporting and CI should not require passing the repository root on the command line when it can be derived from config.

Changes

Configuration (config.yaml)

• Adds mintlify_root: path from the GitHub repository root to the directory that contains support/ and support.mdx (this repo uses ".").
• Adds badge_color: Mintlify <Badge> color (default used in code when missing: "blue"; this repo sets "orange" to preserve prior appearance).

generate_tags.py

• Introduces resolve_mintlify_root(): reads mintlify_root from the loaded config, resolved relative to the GitHub repo root (three parents up from the script path: …/scripts/knowledgebase-nav/ → repo root).
• main(): drops --repo-root; optional --config only (defaults to config.yaml next to the script). Calls resolve_mintlify_root then run_pipeline(repo_root, config_path).
• badge_color flows through tab badges, footers, product index template rendering, and featured section updates.
• templates_root: computed path of templates/ relative to the repo root, passed into Jinja so generated MDX template: metadata is not hard-coded to scripts/knowledgebase-nav/....
• Docstrings and examples generalized (generic Mintlify wording; plain_text doctest examples use neutral names/URLs).

pr_report.py

• Removes --repo-root; git_diff_name_status_head runs with cwd set to the Mintlify root from _resolve_mintlify_root(config_path) (logic duplicated from generate_tags intentionally for standalone imports).
• DEFAULT_CONFIG_PATH: Path(__file__).resolve().parent / "config.yaml".
• --config: help text updated for new behavior.

Jinja templates

• support_tag.mdx.j2 and support_product_index.mdx.j2: dynamic template: path and badge_color for Badges.

GitHub Actions (.github/workflows/knowledgebase-nav.yml)

• Generator and PR report steps invoke python .../generate_tags.py and pr_report.py without --repo-root.
• Header comments describe mintlify_root in config.

Documentation

• README.md and Architecture.md: describe generic <utility>/knowledgebase-nav/ placement, Mintlify root resolution, workflow path filters in terms of Mintlify support/** and the utility directory; local run instructions updated; examples use simplified display names in snippets where appropriate.

Tests

• test_generate_tags.py: mintlify_root / badge_color in fixtures; all updated call sites for new keyword-only parameters; template provenance constant; display name and plain-text test tweaks.
• test_golden_output.py: golden root = resolve_mintlify_root(CONFIG_PATH) instead of assuming repo layout via parent.parent.parent.parent.
• test_pr_report.py: expectations aligned with shortened example display names (Models, Weave).

Breaking changes

• generate_tags.py: --repo-root removed. Set mintlify_root in config.yaml (required).
• pr_report.py: --repo-root removed; git diff runs from the resolved Mintlify root. Any custom invocation must pass --config if config is not beside the script.

Migration notes

• Add to config.yaml: mintlify_root (use "." if support/ and support.mdx are at the repo root) and optionally badge_color.
• Replace python .../generate_tags.py --repo-root . with python .../generate_tags.py (and same for pr_report.py in CI or local scripts).

How to test / verify

• Unit tests:
  pytest scripts/knowledgebase-nav/tests/test_generate_tags.py -v
pytest scripts/knowledgebase-nav/tests/test_pr_report.py -v
• Integration:
  pytest scripts/knowledgebase-nav/tests/test_golden_output.py -v -m integration
  (requires real tree at resolved Mintlify root; skips if support.mdx missing.)
• CI: open or push a PR touching support/** or scripts/knowledgebase-nav/** and confirm Knowledgebase Nav runs without --repo-root and PR comments still list docs.json updates when tag pages change.

Risk / review focus

• resolve_mintlify_root / _resolve_mintlify_root: must stay consistent between generate_tags.py and pr_report.py (called out in code); repo-root assumption is three levels above knowledgebase-nav scripts.
• First run after upgrade: if mintlify_root is missing, both tools fail fast with a clear error (verify config is committed and valid).
• Golden tests: behavior depends on mintlify_root matching this repo’s layout; changing config path semantics later should re-run golden suite.

Stats

• 1 commit: d7b94e586 — Sync kb-nav script with CoreWeave
• 11 files, ~388 insertions, ~197 deletions vs origin/main

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
wandb	🟢 Ready	View Preview	Apr 28, 2026, 10:07 PM

[github-actions]

Knowledgebase navigation update

No updates to support articles, tag pages, or product indexes from this run.

[github-actions]

📚 Mintlify Preview Links

🔗 View Full Preview

📝 Changed (2 total)

⚙️ Other (2)

File
scripts/knowledgebase-nav/Architecture.md
scripts/knowledgebase-nav/README.md

---

🤖 Generated automatically when Mintlify deployment succeeds
📍 Deployment: d7b94e5 at 2026-04-28 22:07:53 UTC