docs: drastically update root README#74
Conversation
The previous README described the docs site as just an OpenAPI
reference for two services. Reality has moved on — this repo now
also orchestrates a five-language auto-doc pipeline (TS/Python/.NET/
Rust/C++) with cross-repo workflow templates, a sync helper, a
local nav splicer, and explicit conventions for MDX safety,
i18n parity, and post-processing.
Rewrite the README to reflect what the repo actually is:
- Mermaid architecture diagram showing the cross-repo flow
(templates → SDK repos → tag push → auto-PR → merge → CDN)
- Repository layout table covering every top-level path
- Auto-doc pipeline section with a tooling-per-language table
and the five canonical templates
- "Updating a template" / "Adding a new SDK" runbooks
- MDX gotchas table (the recurring `{`/`<`/`.md` traps)
- i18n parity expectations
- Validation matrix (mint broken-links, spectral, locale parity,
pwa, codeql) with when to run each
- Troubleshooting table seeded with the issues we hit during the
pipeline build-out
Length 100 → 223 lines. Old content preserved where it was still
accurate (local dev steps, deploy mechanism, license).
|
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. ✨ 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 |
github-actions
Bot
added
area:content
![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 significantly updates the README.md to reflect the project's evolution into a decentralized auto-doc orchestrator. Key additions include an architectural Mermaid diagram, a detailed repository layout, and comprehensive guides for the auto-doc pipeline, internationalization, and local validation. Review feedback focuses on improving the Mermaid diagram's consistency and alphabetical ordering, correcting the JSON path for navigation configuration, and ensuring troubleshooting tips accurately reflect branch naming conventions across SDK repositories.
| TPL["automation/<br/>source-repo-templates/"] | ||
| SYNC["automation/<br/>sync-templates.sh"] | ||
| SPLICE["scripts/<br/>splice-sdk-nav.py"] | ||
| MDX["index.mdx · sdks/*.mdx<br/>quickstart · auth · errors"] |
There was a problem hiding this comment.
The Mermaid diagram node for MDX files uses auth as a shorthand and omits concepts.mdx. For consistency with the 'Repository layout' table and the actual file names, it is better to use the full name authentication and include concepts. Additionally, the list should follow alphabetical ordering to maintain consistency with repository documentation standards.
| MDX["index.mdx · sdks/*.mdx<br/>quickstart · auth · errors"] | |
| MDX["index.mdx · sdks/*.mdx<br/>authentication · concepts · errors · quickstart"] |
References
- When maintaining lists in auto-generated documentation, ensure the generator logic enforces consistent ordering (e.g., alphabetical) to match source-of-truth configuration files like _pages.json.
| "pages": ["index", "your-new-page"] | ||
| } | ||
| ``` | ||
| Add a new page by creating the `.mdx` file, then adding its path (no extension) to the appropriate group in `docs.json`'s `navigation.tabs[*].groups[*].pages`. |
There was a problem hiding this comment.
The navigation path in docs.json is described without the languages level. Since this repository uses a multi-locale configuration, the actual path in the JSON structure is navigation.languages[*].tabs[*].groups[*].pages. Updating this will help contributors find the correct location for navigation changes.
| Add a new page by creating the `.mdx` file, then adding its path (no extension) to the appropriate group in `docs.json`'s `navigation.tabs[*].groups[*].pages`. | |
| Add a new page by creating the .mdx file, then adding its path (no extension) to the appropriate group in docs.json's navigation.languages[*].tabs[*].groups[*].pages. |
| | `mint broken-links` fails on `.md` link targets | Re-run the matching language's `Strip .md extension` post-process step (or just regenerate via the SDK workflow) | | ||
| | Auto-PR has empty content but `pull-request-operation = none` in the run log | The diff fell outside the workflow's `add-paths`. Check that the new files land under `sdks/<lang>/api/**` | | ||
| | Mintlify warns "file does not exist" for a registered page | The splice probably stripped `/index` from a path whose file isn't at `dir/index.md`. Either rename the file or fix the splice's strip rules | | ||
| | sync-templates.sh reports "up-to-date" but no template exists in the target | Check that the target repo's default branch matches the branch hardcoded in `TARGETS` (npm uses `master`, others use `main`) | |
There was a problem hiding this comment.
The troubleshooting tip for sync-templates.sh states that only npm uses the master branch. However, the TARGETS array in automation/sync-templates.sh (line 32) shows that the crates repository (Rust) also uses master as its default branch.
| | sync-templates.sh reports "up-to-date" but no template exists in the target | Check that the target repo's default branch matches the branch hardcoded in `TARGETS` (npm uses `master`, others use `main`) | | |
| | sync-templates.sh reports "up-to-date" but no template exists in the target | Check that the target repo's default branch matches the branch hardcoded in TARGETS (npm and crates use master, others use main) | |
2 participants
Summary
The previous README described the docs site as an OpenAPI reference for two services. Reality has moved on — this repo now also orchestrates a five-language auto-doc pipeline (TS / Python / .NET / Rust / C++) with cross-repo workflow templates, a sync helper, a local nav splicer, and explicit conventions for MDX safety, i18n parity, and post-processing.
Rewrite the README to reflect what the repo actually is.
What's new
add-pathsmisses, splice strip rules, default-branch mismatches, etc.)Length 100 → 223 lines. Old content preserved where it was still accurate (local dev steps, deploy mechanism, license).