feat(core): resolve Markdown file links across plugins (AI-assisted) - #12431
gauranshahuja wants to merge 1 commit into
Conversation
Markdown file references such as [link](../blog/post.md) could only be resolved against the Markdown files of the plugin instance owning the source file. Linking a doc to a blog post or to a standalone page was therefore impossible. The core now builds a site-wide Markdown files registry from the route metadata (`sourceFilePath`), and hands it over to the MDX loader through a new `resolveSiteMarkdownLink` option. Plugins keep resolving their own links in priority, and the site-wide registry is only used as a fallback, so versioned/localized docs keep resolving to the right file. The registry object identity is stable and its content is refreshed in place on site reloads, because the bundler config (and therefore the MDX loader options) is only created once. Closes facebook#9117
|
Hi @gauranshahuja! Thank you for your pull request and welcome to our community. Action RequiredIn order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you. ProcessIn order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA. Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks! |
✅ [V2]Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
I have signed the CLA! |
|
Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks! |
This branch has not been deployed
1 participant
Closes #9117
This PR was written with AI assistance (AI-assisted).
Motivation
Markdown file references such as
[link](../blog/post.md)could only be resolvedagainst the Markdown files of the plugin instance owning the source file. Linking a
doc to a blog post, or a page to a doc, was impossible — the docs even documented the
limitation.
Building on @slorber's "core maintains a file path → URL path mapping" suggestion in
the issue.
Implementation
(
sourceFilePath, available on every content route since refactor(mdx-loader): read metadata from memory (loaded content) instead of fs #10457). No new pluginlifecycle is needed, and multi-instance / versioned / localized content works out of
the box. Third-party content plugins join automatically as soon as they set
sourceFilePathon their routes.LoadContext(siteMarkdownLinks) and handed over to theMDX loader by the docs/blog/pages plugins through a new optional
resolveSiteMarkdownLinkoption.resolveMarkdownLinksremark plugin tries the plugin's own resolver first andonly falls back to the site-wide registry. Existing links therefore keep resolving
exactly as before; only links that are broken today start resolving.
the bundler config (and thus the MDX loader options) is only created once, while
reloadSite()creates a brand newLoadContexton every dev reload.Relative, site-absolute (
/docs/intro.md) and@site/-aliased links are all supported.Test Plan
siteMarkdownLinks.test.ts) including therefresh-in-place invariant used by dev reloads.
resolves / neither resolves.
(docs → blog + pages + site docs, pages → docs + blog, and a new blog post → docs +
pages). Since
onBrokenMarkdownLinksdefaults tothrow, the website build itselfasserts they all resolve.
pnpm test,pnpm lint:js,pnpm lint:style,pnpm lint:spelling,pnpm build:packagesandpnpm build:website:fastall pass.Docs updated:
markdown-features-links.mdxnow has a "Cross-plugin links" sectionreplacing the warning that said this wasn't possible.