fix: absolutize relative doc links and fix $ orphan in version interpolations#593
Merged
Conversation
… `$` in version interpolations
Two bugs in the exported `.md` output that hurt LLM consumption:
1. Relative links (`./foo`, `../foo`, `.mdx` references) stayed relative
in the exported file. An LLM fetching `/docs/<page>.md` standalone
has no base URL to resolve them against, so the links are dead.
Now resolved against the current doc's URL path and rewritten to
absolute `https://<site>/docs/<...>.md` URLs. `.mdx` references are
also normalized to `.md`. External, anchor-only, and asset links
are left untouched, and rewriting skips fenced code blocks and
inline code spans.
2. `replaceVersionInterpolations` matched `{versions.X}` but not the
`$` of `${versions.X}`. JSX template-literal usages like
`<Link to={`.../${versions.githubRef}/...`}>` survived the earlier
`<Link>` extraction with the `{...}` portion already replaced and
the `$` left behind, producing URLs like `tree/$main/samples`.
Regex now optionally consumes the leading `$`.
Signed-off-by: Rashad Sirajudeen <rashad@wso2.com>
Contributor
📝 WalkthroughSummary by CodeRabbitRelease Notes
WalkthroughThe plugin now extracts site configuration ( ChangesMarkdown Link URL Rewriting
🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 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 |
rashadism
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plugins/docusaurus-plugin-markdown-export/mdxProcessor.js (1)
83-84:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUpdate step number to maintain sequential numbering.
Line 83 should say "Step 12" instead of "Step 11" now that a new Step 10 was added above.
📝 Proposed fix
- // Step 11: Clean up excessive whitespace + // Step 12: Clean up excessive whitespace result = cleanupWhitespace(result);🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plugins/docusaurus-plugin-markdown-export/mdxProcessor.js` around lines 83 - 84, Update the inline comment before the cleanupWhitespace call to reflect the new sequence number: change "Step 11: Clean up excessive whitespace" to "Step 12: Clean up excessive whitespace" in mdxProcessor.js so comments remain sequential; the affected line is the comment immediately above the statement "result = cleanupWhitespace(result);" which you should update.
🧹 Nitpick comments (1)
plugins/docusaurus-plugin-markdown-export/mdxProcessor.js (1)
318-335: 💤 Low valueConsider documenting the absolute-path assumption.
The
resolvePathfunction works correctly for its current use case where paths are always absolute (e.g.,/docs/foo/../bar), but it doesn't handle standalone relative paths correctly (e.g.,foo/../barwould becomefoo/barinstead ofbar). Since the function is always called with absolute paths (line 312 prependsbaseDir + '/'), this is not a bug, but future maintainers might find the behavior surprising.💡 Optional: Add a JSDoc comment
+/** + * Normalize an absolute path by collapsing '.', '..', and '//' segments. + * Note: This function expects absolute paths (starting with '/'). + */ function resolvePath(p) {🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plugins/docusaurus-plugin-markdown-export/mdxProcessor.js` around lines 318 - 335, The resolvePath function assumes POSIX-style absolute paths and can produce surprising results for standalone relative inputs; add a JSDoc comment above the resolvePath function that clearly states the function expects an absolute POSIX path (e.g., "/docs/foo/../bar"), describes how it collapses ".", "..", and duplicate slashes, shows a short example of expected input/output, and documents the return value (normalized absolute path or "/"). Also mention that callers (e.g., where baseDir + '/' is prepended) must ensure paths are absolute so future maintainers know the precondition.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@plugins/docusaurus-plugin-markdown-export/mdxProcessor.js`:
- Around line 83-84: Update the inline comment before the cleanupWhitespace call
to reflect the new sequence number: change "Step 11: Clean up excessive
whitespace" to "Step 12: Clean up excessive whitespace" in mdxProcessor.js so
comments remain sequential; the affected line is the comment immediately above
the statement "result = cleanupWhitespace(result);" which you should update.
---
Nitpick comments:
In `@plugins/docusaurus-plugin-markdown-export/mdxProcessor.js`:
- Around line 318-335: The resolvePath function assumes POSIX-style absolute
paths and can produce surprising results for standalone relative inputs; add a
JSDoc comment above the resolvePath function that clearly states the function
expects an absolute POSIX path (e.g., "/docs/foo/../bar"), describes how it
collapses ".", "..", and duplicate slashes, shows a short example of expected
input/output, and documents the return value (normalized absolute path or "/").
Also mention that callers (e.g., where baseDir + '/' is prepended) must ensure
paths are absolute so future maintainers know the precondition.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: b93614ff-129c-45f1-a804-f77218b1307f
📒 Files selected for processing (2)
plugins/docusaurus-plugin-markdown-export/index.jsplugins/docusaurus-plugin-markdown-export/mdxProcessor.js
LakshanSS
approved these changes
May 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
./foo,../foo,.mdx) in exported.mdfiles were left relative, so consumers fetching a single.mdhad no base URL to resolve against. Now rewritten to absolutehttps://<site>/docs/<...>.mdURLs against the doc's own location.replaceVersionInterpolationsmatched{versions.X}but not the$of${versions.X}, leaving a stray$in the output (e.g.tree/$main/samples). Regex now optionally consumes the leading$.Sample
Before:
After:
Test plan
npm run buildproduces.mdfiles with absolute URLs for relative doc links..mdxreferences in source render as.mdin the export.${versions.githubRef}in<Link to={...}>resolves cleanly with no leftover$.