From bbec801e3fbcf7c7c30154bbfaf2dbe9d5302712 Mon Sep 17 00:00:00 2001
From: Kohei Watanabe <nebel@fogtype.com>
Date: Fri, 21 Nov 2025 05:38:15 +0900
Subject: [PATCH] fix(mdx-loader): fix url.parse deprecation warning on Node
 24+ (#11530)

Co-authored-by: sebastien <lorber.sebastien@gmail.com>
---
 .../src/remark/transformImage/index.ts            | 12 ++++++------
 .../src/remark/transformLinks/index.ts            | 15 ++++++++-------
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts b/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts
index 1dc00aa894..ff88403eef 100644
--- a/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts
+++ b/packages/docusaurus-mdx-loader/src/remark/transformImage/index.ts
@@ -6,7 +6,6 @@
  */
 
 import path from 'path';
-import url from 'url';
 import fs from 'fs-extra';
 import {
   toMessageRelativeFilePath,
@@ -15,6 +14,7 @@ import {
   findAsyncSequential,
   getFileLoaderUtils,
   parseURLOrPath,
+  parseLocalURLPath,
 } from '@docusaurus/utils';
 import escapeHtml from 'escape-html';
 import {imageSizeFromFile} from 'image-size/fromFile';
@@ -207,11 +207,11 @@ async function processImageNode(target: Target, context: Context) {
     return;
   }
 
-  const parsedUrl = url.parse(node.url);
-  if (parsedUrl.protocol || !parsedUrl.pathname) {
-    // pathname:// is an escape hatch, in case user does not want her images to
+  const localUrlPath = parseLocalURLPath(node.url);
+  if (!localUrlPath) {
+    // pathname:// is an escape hatch, in case the user does not want images to
     // be converted to require calls going through webpack loader
-    if (parsedUrl.protocol === 'pathname:') {
+    if (parseURLOrPath(node.url).protocol === 'pathname:') {
       node.url = node.url.replace('pathname://', '');
     }
     return;
@@ -220,7 +220,7 @@ async function processImageNode(target: Target, context: Context) {
   // We decode it first because Node Url.pathname is always encoded
   // while the image file-system path are not.
   // See https://github.com/facebook/docusaurus/discussions/10720
-  const decodedPathname = decodeURIComponent(parsedUrl.pathname);
+  const decodedPathname = decodeURIComponent(localUrlPath.pathname);
 
   // We try to convert image urls without protocol to images with require calls
   // going through webpack ensures that image assets exist at build time
diff --git a/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts b/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts
index 5d2d2d2d95..192c1e9f8c 100644
--- a/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts
+++ b/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts
@@ -6,7 +6,6 @@
  */
 
 import path from 'path';
-import url from 'url';
 import fs from 'fs-extra';
 import {
   toMessageRelativeFilePath,
@@ -15,6 +14,7 @@ import {
   findAsyncSequential,
   getFileLoaderUtils,
   parseURLOrPath,
+  parseLocalURLPath,
 } from '@docusaurus/utils';
 import escapeHtml from 'escape-html';
 import logger from '@docusaurus/logger';
@@ -209,21 +209,22 @@ async function processLinkNode(target: Target, context: Context) {
     return;
   }
 
-  const parsedUrl = url.parse(node.url);
-  if (parsedUrl.protocol || !parsedUrl.pathname) {
+  const localUrlPath = parseLocalURLPath(node.url);
+  if (!localUrlPath) {
     // Don't process pathname:// here, it's used by the <Link> component
     return;
   }
-  const hasSiteAlias = parsedUrl.pathname.startsWith('@site/');
+
+  const hasSiteAlias = localUrlPath.pathname.startsWith('@site/');
   const hasAssetLikeExtension =
-    path.extname(parsedUrl.pathname) &&
-    !parsedUrl.pathname.match(/\.(?:mdx?|html)(?:#|$)/);
+    path.extname(localUrlPath.pathname) &&
+    !localUrlPath.pathname.match(/\.(?:mdx?|html)(?:#|$)/);
   if (!hasSiteAlias && !hasAssetLikeExtension) {
     return;
   }
 
   const localFilePath = await getLocalFileAbsolutePath(
-    decodeURIComponent(parsedUrl.pathname),
+    decodeURIComponent(localUrlPath.pathname),
     context,
   );