fix(mdx-loader): report vfile messages from Remark plugins

[inancsege]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes Error messages set to vfile by Remark plugins are not reported. #9953) and the maintainers have approved on my working plan.

Disclosure: this change was written with AI assistance. I reviewed the code, ran the verification myself and take responsibility for it.

Motivation

Fixes #9953

Remark and Rehype plugins report non-fatal problems by attaching messages to the vfile via file.message(...) rather than by throwing. Those messages accumulate on result.messages, but the MDX processor discarded them:

return mdxProcessor.process(vfile).then((result) => ({
  content: result.toString(),
  data: result.data,
}));

So warnings emitted by third-party Remark plugins through the standard Unified reporting API were invisible to users. Fatal messages (file.fail(...)) already throw and are surfaced by compileToJSX, so this only concerns the non-fatal path.

From the issue:

Agree we should have that 👍

Historically we never used those Unified/Vfile reporting APIs, but we should

Changes

• processor.ts now exposes the vfile messages on SimpleProcessorResult instead of dropping them.
• New reportMDXMessages() in messages.ts formats and logs them, following the existing logger conventions.
• loader.ts calls it after compilation.

Reporting is restricted to the client compiler so prod builds do not emit each warning twice. This mirrors the existing logic in the unusedDirectives Remark plugin.

Example output, for a plugin calling file.message('Some plugin warning', ...):

[WARNING] Docusaurus found 2 Markdown warnings in file "docs/test.md"
- Some plugin warning (3:5)
- Another warning without position

No new configuration option is introduced. If you would rather have this gated behind a siteConfig.markdown.hooks severity option than a plain warning, I am happy to follow up.

Test Plan

New unit tests:

• __tests__/processor.test.ts: the processor returns messages reported by a Remark plugin. This file previously contained no tests, as the old TODO about Jest and ESM no longer applies under Vitest.
• __tests__/messages.test.ts: formatting including line and column, the empty case, and the server compiler case.
• __tests__/loader.test.ts: end to end through mdxLoader, asserting the warning reaches console.warn.

Verified locally:

• vitest run: 185 test files, 2965 tests passing
• tsc --noEmit -p packages/docusaurus-mdx-loader/tsconfig.json: clean
• eslint "packages/docusaurus-mdx-loader/src/**/*.ts": no errors
• oxfmt --list-different: clean

Each test was confirmed to fail before the corresponding change was applied.

Test links

This is a build-time logging change with no UI impact, so there is no relevant deploy preview page.

Related issues/PRs

Fixes #9953

[meta-cla]

Hi @inancsege!

Thank you for your pull request and welcome to our community.

Action Required

In 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.

Process

In 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 CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@meta.com. Thanks!

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	14dffc4
🔍 Latest deploy log	https://app.netlify.com/projects/docusaurus-2/deploys/6a9662933c680e00089c617d
😎 Deploy Preview	https://deploy-preview-12399--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[meta-cla]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!