chore(cli): polish checkDeadLinks logs (#2350)

SoonIter · web-flow · commit bc26912ec942 · 2025-07-04T17:19:35.000+08:00
diff --git a/packages/core/src/node/logger/hint.ts b/packages/core/src/node/logger/hint.ts
@@ -97,3 +97,14 @@ export function hintNavJsonChangeThenPanic(
     process.exit(1);
   }
 }
+
+let isLogged = false;
+export function hintRelativeMarkdownLink() {
+  if (isLogged) {
+    return;
+  }
+  isLogged = true;
+  logger.info(
+    '[Rspress v2] Markdown links without "./" prefix are now relative links, e.g: [](guide/getting-started) is equal to [](./guide/getting-started). You can rewrite it to [](/guide/getting-started) to always use absolute links, or use [](./getting-started.md)',
+  );
+}
diff --git a/packages/core/src/node/mdx/remarkPlugins/normalizeLink.ts b/packages/core/src/node/mdx/remarkPlugins/normalizeLink.ts
@@ -15,37 +15,49 @@ import type { Plugin } from 'unified';
 import { visit } from 'unist-util-visit';
 
 import { logger } from '@rspress/shared/logger';
+import picocolors from 'picocolors';
+import { hintRelativeMarkdownLink } from '../../logger/hint';
 import type { RouteService } from '../../route/RouteService';
 import { getASTNodeImport } from '../../utils';
 
+// TODO: checkDeadLinks support external links and anchor hash links
 function checkDeadLinks(
   internalLinks: Map<string, string>,
   filePath: string,
   routeService: RouteService,
 ) {
-  const errorInfos: string[] = [];
-  internalLinks.entries().forEach(([nodeUrl, link]) => {
+  const errorInfos: [string, string][] = [];
+
+  let possibleBreakingChange = false;
+
+  [...internalLinks.entries()].forEach(([nodeUrl, link]) => {
     const cleanLinkPath = linkToRoutePath(link);
     if (!cleanLinkPath) {
       return;
     }
 
+    if (!nodeUrl.startsWith('/') && /^\w/.test(nodeUrl)) {
+      possibleBreakingChange = true;
+    }
+
     // allow fuzzy matching, e.g: /guide/ and /guide is equal
     // This is a simple judgment, the performance will be better than "matchPath" in react-router-dom
     if (
       !routeService.isExistRoute(removeTrailingSlash(cleanLinkPath)) &&
       !routeService.isExistRoute(addTrailingSlash(cleanLinkPath))
     ) {
-      errorInfos.push(
-        `Internal link to "${nodeUrl}" which points to "${cleanLinkPath}" is dead, check it in "${filePath}"`,
-      );
+      errorInfos.push([nodeUrl, link]);
     }
   });
   // output error info
   if (errorInfos.length > 0) {
-    errorInfos?.forEach(err => {
-      logger.error(err);
-    });
+    if (possibleBreakingChange) {
+      hintRelativeMarkdownLink();
+    }
+
+    logger.error(`Dead links found in ${picocolors.cyan(filePath)}:
+${errorInfos.map(([nodeUrl, link]) => `  ${picocolors.green(`"[..](${nodeUrl})"`)} ${picocolors.gray(link)}`).join('\n')}`);
+
     if (isProduction()) {
       throw new Error('Dead link found');
     }
