feat(nav): wire generated SDK API references into SDKs tab#17
feat(nav): wire generated SDK API references into SDKs tab#17WomB0ComB0 merged 2 commits intomainfrom
Conversation
Adds a "Generated API reference" group under the SDKs tab pointing at the entry pages of the auto-generated TypeDoc and DefaultDocumentation trees: - sdks/typescript/api/README — @resq-sw/ui surface - sdks/dotnet/api/README — six packable .NET projects The READMEs link out to per-component / per-type pages so a single nav entry per language is enough; the api-docs workflows already keep the file tree in sync on every release tag.
github-actions
Bot
added
area:content
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughUpdated ChangesDocumentation Navigation Configuration
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds a new 'Generated API reference' section to the documentation configuration, linking the TypeScript and .NET SDK API READMEs. The reviewer suggested using explicit labels for the navigation items to ensure consistency with other language groups and recommended changing the group title to Title Case for better alignment with existing documentation patterns.
* Capitalize "Generated API Reference" to match the convention
used by sibling groups like "Infrastructure API".
* Wrap each language entry in its own group so the sidebar label
is "TypeScript" / ".NET" rather than the README's H1
("@resq-sw/ui" / "ResQ .NET SDK"). Uses standard Mintlify
nested-group syntax instead of the {page, label} shape from
the suggestion, which is not part of Mintlify's docs.json
schema.
Mintlify's nav resolver only matches .mdx for page ids in docs.json. Without renaming the three nav-registered SDK READMEs, mint dev warns: "sdks/<lang>/api/README" is referenced in the docs.json navigation but the file does not exist. Scope is limited to the three top-level entry pages: - sdks/typescript/api/README.md -> .mdx - sdks/dotnet/api/README.md -> .mdx - sdks/python/api/README.md -> .mdx Submodule pages (per-component, per-class, per-module .md files in the auto-generated trees) stay as .md. Mintlify treats in-content (path.md) links as page references and resolves them against on-disk files; explicit .mdx in those links would be treated as static-asset references and trip broken-links. Only the nav-registered files need to be .mdx. Also add a Python entry under "Generated API Reference" so the Python tree is reachable from the SDKs tab the same way TypeScript and .NET are. PR #17 added TS and .NET; Python landed on main after that PR was opened. Replaces an earlier wholesale rename (commits 4e31133, 7301dbc) that renamed every .md in the api/ trees and tripped 3832 broken-links validation failures because Mintlify rejects explicit .mdx in in-content links. Both prior commits remain in the branch reflog.
Single-line nav addition — points at sdks/python/api/README which Mintlify resolves via the existing .md file. No file renames; the auto-generated trees stay as .md because Mintlify's .md link resolver is filesystem-based and already accepts the cross-references TypeDoc / DefaultDocumentation / pydoc-markdown emit. Renaming the READMEs to .mdx (attempted in earlier commits 4e31133 / 7301dbc / 54934ef) was the wrong move — .mdx parents have stricter link resolution that requires every link target to be nav-registered, which is not feasible for 3500+ auto-generated pages. The "is referenced in docs.json navigation but the file does not exist" warning that mint dev emits for .md-extension README references is cosmetic; Mintlify still renders the page. The "Generated API Reference" group from PR #17 only had TypeScript and .NET sub-groups; PR #18 (Python template) and the resulting auto-PRs (#19, #20) landed the Python content after that PR was opened.
Single-line nav addition — points at sdks/python/api/README which Mintlify resolves via the existing .md file. No file renames; the auto-generated trees stay as .md because Mintlify's .md link resolver is filesystem-based and already accepts the cross-references TypeDoc / DefaultDocumentation / pydoc-markdown emit. Renaming the READMEs to .mdx (attempted in earlier commits 4e31133 / 7301dbc / 54934ef) was the wrong move — .mdx parents have stricter link resolution that requires every link target to be nav-registered, which is not feasible for 3500+ auto-generated pages. The "is referenced in docs.json navigation but the file does not exist" warning that mint dev emits for .md-extension README references is cosmetic; Mintlify still renders the page. The "Generated API Reference" group from PR #17 only had TypeScript and .NET sub-groups; PR #18 (Python template) and the resulting auto-PRs (#19, #20) landed the Python content after that PR was opened. Co-authored-by: Mike Odnis <engineer@resq.software>
2 participants
Summary
Adds a Generated API reference group under the SDKs tab pointing at the entry pages of the auto-generated TypeDoc and DefaultDocumentation trees:
sdks/typescript/api/README(the@resq-sw/uisurface, 3,500+ pages)sdks/dotnet/api/README(the six packable .NET projects)Why now
Both api-docs workflows are landing real content on every release tag, but the generated trees were unreachable from site nav (
docs.resq.software/sdks/typescript/apireturned 404 even though the files existed). One nav entry per language is enough because the README in each tree links out to every per-component / per-type page.Why a single entry vs full nested nav
Mintlify's
directoryproperty is a display option (accordion/card/none) for index pages, not auto-discovery. Listing 3,500+ TypeScript pages and several hundred .NET pages indocs.jsonwould be churn on every release. The single-entry approach lets users land at the README and click through; full programmatic nav splice (consume the_pages.jsonartifacts the workflows already emit) is a worthwhile follow-up but real engineering.Test plan
mintlify (broken links)should stay green (the README contents have already passed it on the auto-PRs).Summary by CodeRabbit