fix(templates): emit .mdx so Mintlify nav resolves auto-gen pages#22
fix(templates): emit .mdx so Mintlify nav resolves auto-gen pages#22WomB0ComB0 wants to merge 1 commit intomainfrom
Conversation
|
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. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThree API documentation workflows for .NET, Python, and TypeScript are updated to rename generated Markdown files from ChangesMDX Extension and Link Rewriting for Mintlify Navigation
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 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 introduces a step to rename generated Markdown files from .md to .mdx and update internal links across the .NET, Python, and TypeScript documentation workflows to satisfy Mintlify's navigation requirements. Feedback recommends standardizing the explanatory comments across all templates for consistency. Furthermore, there is a concern that the regex-based link replacement script does not account for code blocks or inline code spans, which could lead to unintended modifications of documentation examples.
| # Mintlify's docs.json nav resolver only matches .mdx. | ||
| # Leaving the tree as .md makes `mint dev` warn that | ||
| # nav-registered files do not exist. Rename every .md and | ||
| # rewrite the matching `(path.md)` / `(path.md#anchor)` | ||
| # link targets in place. |
There was a problem hiding this comment.
For clarity and consistency with the TypeScript template, consider adding the note that Mintlify accepts both extensions for in-content links, but requires .mdx for the navigation resolver. This helps explain why the link rewrite is beneficial but perhaps not as critical as the file rename.
# Mintlify accepts both .md and .mdx for in-content links,
# but its docs.json navigation resolver only matches .mdx.
# Leaving the tree as .md makes mint dev warn that
# nav-registered files do not exist. Rename every .md and
# rewrite the matching (path.md) / (path.md#anchor)
# link targets in place.| python3 - <<'PY' | ||
| import pathlib, re | ||
| LINK = re.compile(r'(\]\()((?!https?://|mailto:|#|/)[^)\s]*?)(\.md)((?:#[^)]*)?)(\))') | ||
| for p in pathlib.Path(".").rglob("*.mdx"): | ||
| text = p.read_text(encoding="utf-8") | ||
| new = LINK.sub(r'\1\2.mdx\4\5', text) | ||
| if new != text: | ||
| p.write_text(new, encoding="utf-8") | ||
| PY |
There was a problem hiding this comment.
The Python script for link rewriting does not respect Markdown code blocks or inline code spans. Per the general rules, post-processing should avoid modifying content inside code regions to prevent breaking examples. Consider using a more robust parsing approach (e.g., splitting by code fences) if literal link syntax is expected in the documentation prose.
References
- When processing Markdown/MDX files to escape curly braces for JSX compatibility, ensure the logic ignores content within inline code spans (backticks) to prevent breaking code snippets.
| # Mintlify's docs.json nav resolver only matches .mdx. | ||
| # Leaving the tree as .md makes `mint dev` warn that | ||
| # nav-registered files do not exist. Rename every .md and | ||
| # rewrite the matching `(path.md)` / `(path.md#anchor)` | ||
| # link targets in place. |
There was a problem hiding this comment.
For clarity and consistency with the TypeScript template, consider adding the note that Mintlify accepts both extensions for in-content links, but requires .mdx for the navigation resolver.
# Mintlify accepts both .md and .mdx for in-content links,
# but its docs.json navigation resolver only matches .mdx.
# Leaving the tree as .md makes mint dev warn that
# nav-registered files do not exist. Rename every .md and
# rewrite the matching (path.md) / (path.md#anchor)
# link targets in place.| python3 - <<'PY' | ||
| import pathlib, re | ||
| LINK = re.compile(r'(\]\()((?!https?://|mailto:|#|/)[^)\s]*?)(\.md)((?:#[^)]*)?)(\))') | ||
| for p in pathlib.Path(".").rglob("*.mdx"): | ||
| text = p.read_text(encoding="utf-8") | ||
| new = LINK.sub(r'\1\2.mdx\4\5', text) | ||
| if new != text: | ||
| p.write_text(new, encoding="utf-8") | ||
| PY |
There was a problem hiding this comment.
The Python script for link rewriting does not respect Markdown code blocks or inline code spans. Per the general rules, post-processing should avoid modifying content inside code regions to prevent breaking examples. Consider using a more robust parsing approach if literal link syntax is expected in the documentation prose.
References
- When processing Markdown/MDX files to escape curly braces for JSX compatibility, ensure the logic ignores content within inline code spans (backticks) to prevent breaking code snippets.
| python3 - <<'PY' | ||
| import pathlib, re | ||
| LINK = re.compile(r'(\]\()((?!https?://|mailto:|#|/)[^)\s]*?)(\.md)((?:#[^)]*)?)(\))') | ||
| for p in pathlib.Path(".").rglob("*.mdx"): | ||
| text = p.read_text(encoding="utf-8") | ||
| new = LINK.sub(r'\1\2.mdx\4\5', text) | ||
| if new != text: | ||
| p.write_text(new, encoding="utf-8") | ||
| PY |
There was a problem hiding this comment.
The Python script for link rewriting does not respect Markdown code blocks or inline code spans. Per the general rules, post-processing should avoid modifying content inside code regions to prevent breaking examples. Consider using a more robust parsing approach if literal link syntax is expected in the documentation prose.
References
- When processing Markdown/MDX files to escape curly braces for JSX compatibility, ensure the logic ignores content within inline code spans (backticks) to prevent breaking code snippets.
Previous approach (commits 229acac, 84cbf4e on origin) renamed every .md in the auto-generated tree to .mdx and rewrote in-content link targets. The wholesale rename tripped Mintlify's broken-links validation with 3832 broken-link errors because Mintlify rejects explicit `.mdx` extensions in in-content links (treats them as static-asset references rather than page references). The previous attempt to fix the link form (strip .md from targets, leave them extensionless) didn't help either: Mintlify's broken-links also requires nav registration for any non-.md link. Scope the rename to ONLY the three files Mintlify's nav resolver actually looks for: - TypeScript: add a tiny `mv README.md README.mdx` step at the end (typedoc-plugin-markdown emits the README itself, so we rename the result rather than redirecting the generator). - .NET: change the `Write top-level index` step's redirect target from `README.md` to `README.mdx`. - Python: same as .NET. Submodule pages stay .md. Mintlify treats their `(path.md)` in-content links as page references and resolves them on disk regardless of extension, so they continue to render correctly. Pairs with #21 (one-shot rename of the same three READMEs in the existing tree).
WomB0ComB0
force-pushed
the
feat/templates-emit-mdx
branch
from
84cbf4e to
0a3b79a
Compare
|
Closing — analysis on docs#21 showed the .mdx-rename was the wrong fix. Mintlify's .mdx parent files have stricter link resolution that breaks the auto-generated cross-references (3832 broken-links errors), whereas .md parents resolve filesystem-style and pass cleanly. The 'is referenced in nav but does not exist' warning from mint dev is cosmetic; Mintlify still renders the page. Templates stay emitting .md, no change needed. |
2 participants
Summary
Each language template (
api-docs.typescript.yml,api-docs.dotnet.yml,api-docs.python.yml) now ends with a.md -> .mdxrename + relative-link rewrite step, run after the pages-index builder.Without this, the next regen force-pushes
.mdcontent into the docs repo andmint devwarns:Mintlify's nav resolver matches only
.mdxfor page ids indocs.json. In-content links accept either extension, but nav does not.Why this insertion point
The rename runs after
_pages.jsonis built so the index paths (which are already extensionless) are stable. Earlier post-processing steps (breadcrumb strip, bare-filename./prefix, MDX curly-brace escape) all target.mdand run unchanged. The link-rewrite uses a paren-aware Python regex that skips external URLs (http://,https://,mailto:) and absolute paths (/).Pairs with
npm,dotnet-sdk,pypi) so the running workflows pick this up. Without those syncs, the next regen still emits.mdand undoes feat(nav): add Python entry under Generated API Reference #21.Test plan
mint devno longer warns about missing nav-registered files.Summary by CodeRabbit