feat(md-enhance): rename linkCheck to linksCheck, close #3094

BREAKING CHANGE: licksCheck now supports `ignore` to ignore some links

docs/md-enhance/src/config.md

@@ -44,19 +44,31 @@ The last 4 items conflict with default theme and will override its style.
 
 :::
 
-## linkCheck
+## linksCheck
 
-- Type: `"always" | "dev" | "build" | "never" | boolean`
-- Default: `"dev"`
+- Type: `LinksCheckOptions`
 
-Whether to enable link check.
+  ```ts
+  type LinksCheckStatus = "always" | "dev" | "build" | "never";
 
-::: note
+  interface LinksCheckOptions {
+    /**
+     * Whether check dead links in markdown
+     *
+     * @default "dev"
+     */
+    status?: LinksCheckStatus;
 
-- `true` equals to `'always'`
-- `false` equals to `'never'`
+    /**
+     * Dead links to ignore
+     */
+    ignore?: (string | RegExp)[] | ((link: string, isDev: boolean) => boolean);
+  }
+  ```
 
-:::
+- Default: `{ status: "dev" }`
+
+Whether to enable links check.
 
 ## vPre
 

docs/md-enhance/src/zh/config.md

@@ -44,19 +44,31 @@ icon: gears
 
 :::
 
-## linkCheck
+## linksCheck
 
-- 类型: `"always" | "dev" | "build" | "never" | boolean`
-- 默认值: `"dev"`
+- 类型: `LinksCheckOptions`
 
-是否启用链接检查。
+  ```ts
+  type LinksCheckStatus = "always" | "dev" | "build" | "never";
 
-::: note
+  interface LinksCheckOptions {
+    /**
+     * 是否检查 Markdown 中的死链
+     *
+     * @default "dev"
+     */
+    status?: LinksCheckStatus;
 
-- `true` 等同于 `'always'`
-- `false` 等同于 `'never'`
+    /**
+     * 忽略的死链
+     */
+    ignore?: (string | RegExp)[] | ((link: string, isDev: boolean) => boolean);
+  }
+  ```
 
-:::
+- 默认值: `{ status: "dev" }`
+
+是否启用链接检查。
 
 ## vPre
 

packages/md-enhance/__tests__/unit/linkCheck.spec.ts → packages/md-enhance/__tests__/unit/linksCheck.spec.ts

@@ -3,7 +3,7 @@ import { path } from "@vuepress/utils";
 import { it } from "vitest";
 
 import { emptyTheme } from "./__fixtures__/theme/empty.js";
-import { checkLinks } from "../../src/node/checkLink.js";
+import { linksCheck } from "../../src/node/linksCheck.js";
 
 it("should check links correctly", async () => {
   const app = createBaseApp({
@@ -14,5 +14,5 @@ it("should check links correctly", async () => {
 
   await app.init();
 
-  app.pages.forEach((page) => checkLinks(page, app));
+  app.pages.forEach((page) => linksCheck(page, app, () => false));
 });

packages/md-enhance/src/node/compact/convert.ts

@@ -1,5 +1,11 @@
+import { colors } from "@vuepress/utils";
+
 import { deprecatedLogger, droppedLogger } from "./utils.js";
-import { type MarkdownEnhanceOptions } from "../options.js";
+import {
+  type LinksCheckStatus,
+  type MarkdownEnhanceOptions,
+} from "../options.js";
+import { logger } from "../utils.js";
 
 /** @deprecated */
 export const convertOptions = (
@@ -53,4 +59,21 @@ export const convertOptions = (
   droppedLogger(options, "enableAll");
   droppedLogger(options, "lineNumbers");
   droppedLogger(options, "imageFix");
+
+  if ("linkCheck" in options) {
+    logger.warn(
+      `${colors.magenta(
+        "linkCheck"
+      )} is deprecated, please use ${colors.magenta("checkLinks")} instead`
+    );
+
+    options.checkLinks = {
+      status:
+        typeof options["linkCheck"] === "boolean"
+          ? options["linkCheck"]
+            ? "always"
+            : "never"
+          : (options["linkCheck"] as LinksCheckStatus),
+    };
+  }
 };

packages/md-enhance/src/node/linksCheck.ts

@@ -0,0 +1,82 @@
+import { type App, type Page } from "@vuepress/core";
+import { logger } from "@vuepress/utils";
+import {
+  isAbsoluteUrl,
+  isArray,
+  isFunction,
+  isRegExp,
+} from "vuepress-shared/node";
+
+import { type MarkdownEnhanceOptions } from "./options.js";
+
+export const getLinksCheckStatus = (
+  app: App,
+  options: Partial<MarkdownEnhanceOptions>
+): {
+  enabled: boolean;
+  isIgnoreLink: (link: string, isDev: boolean) => boolean;
+} => {
+  const { status = "dev", ignore = [] } = options.checkLinks || {};
+
+  const isIgnoreLink = isFunction(ignore)
+    ? ignore
+    : isArray(ignore)
+    ? (link: string): boolean =>
+        ignore.some((item) =>
+          isRegExp(item) ? item.test(link) : item === link
+        )
+    : (): boolean => false;
+
+  return {
+    enabled:
+      // always check
+      status === "always" ||
+      // enable in dev
+      (app.env.isDev && status === "dev") ||
+      // enabled in build
+      (app.env.isBuild && status === "build") ||
+      false,
+    isIgnoreLink,
+  };
+};
+
+export const linksCheck = (
+  page: Page,
+  app: App,
+  isIgnoreLink: (link: string, isDev: boolean) => boolean
+): void => {
+  const path = page.filePathRelative || page.path;
+  const { pages } = app;
+
+  const markdownLinks = page.links.filter(({ raw }) =>
+    raw.match(/.md((?:\?|#).*)?$/)
+  );
+
+  const brokenLinks = [
+    ...markdownLinks
+      // relative markdown links
+      .filter(({ raw }) => !isAbsoluteUrl(raw))
+      .filter(
+        ({ relative }) =>
+          // check whether the page exists
+          pages.every(
+            ({ filePathRelative }) => filePathRelative !== decodeURI(relative)
+          ) && !isIgnoreLink(relative, app.env.isDev)
+      ),
+    ...markdownLinks
+      // absolute markdown links
+      .filter(({ raw }) => isAbsoluteUrl(raw))
+      .filter(({ absolute }) =>
+        // check whether the page exists
+        pages.every(
+          ({ filePathRelative }) =>
+            !filePathRelative ||
+            (`${app.options.base}${filePathRelative}` !== decodeURI(absolute) &&
+              !isIgnoreLink(absolute, app.env.isDev))
+        )
+      ),
+  ].map(({ raw }) => raw);
+
+  if (brokenLinks.length)
+    logger.warn(`Broken links found in ${path}: ${brokenLinks.join(", ")}`);
+};

packages/md-enhance/src/node/options.ts

@@ -21,18 +21,36 @@ import {
   type VuePlaygroundOptions,
 } from "../shared/index.js";
 
+export type LinksCheckStatus = "always" | "dev" | "build" | "never";
+
+export interface LinksCheckOptions {
+  /**
+   * Whether check dead links in markdown
+   *
+   * 是否检查 Markdown 中的死链
+   *
+   * @default "dev"
+   */
+  status?: LinksCheckStatus;
+
+  /**
+   * Dead links to ignore
+   *
+   * 忽略的死链
+   */
+  ignore?: (string | RegExp)[] | ((link: string, isDev: boolean) => boolean);
+}
+
 /**
  * md-enhance plugin configuration
  */
 export interface MarkdownEnhanceOptions {
   /**
    * Whether check dead links in markdown
    *
-   * @description `true` equals to `"always"`, `false` equals to `"never"`
-   *
-   * @default "dev"
+   * @default { status: "dev"}
    */
-  linkCheck?: "always" | "dev" | "build" | "never" | boolean;
+  checkLinks?: LinksCheckOptions;
 
   /**
    * Whether enable standard GFM support

packages/md-enhance/src/node/plugin.ts

@@ -34,14 +34,14 @@ import {
   isPlainObject,
 } from "vuepress-shared/node";
 
-import { checkLinks, getCheckLinksStatus } from "./checkLink.js";
 import {
   convertOptions,
   legacyCodeDemo,
   legacyCodeGroup,
   legacyFlowchart,
   legacyInclude,
 } from "./compact/index.js";
+import { getLinksCheckStatus, linksCheck } from "./linksCheck.js";
 import { markdownEnhanceLocales } from "./locales.js";
 import {
   CODE_DEMO_DEFAULT_SETTING,
@@ -117,7 +117,10 @@ export const mdEnhancePlugin =
     const mathjaxEnable = getStatus("mathjax");
     const vuePlaygroundEnable = getStatus("vuePlayground");
 
-    const shouldCheckLinks = getCheckLinksStatus(app, options);
+    const { enabled: linksCheckEnabled, isIgnoreLink } = getLinksCheckStatus(
+      app,
+      options
+    );
 
     const katexOptions: KatexOptions<MarkdownEnv> = {
       macros: {
@@ -371,15 +374,16 @@ export const mdEnhancePlugin =
       },
 
       extendsPage: (page, app): void => {
-        if (shouldCheckLinks && isAppInitialized) checkLinks(page, app);
+        if (linksCheckEnabled && isAppInitialized)
+          linksCheck(page, app, isIgnoreLink);
         if (includeEnable)
           page.deps.push(...(<string[]>page.markdownEnv["includedFiles"]));
       },
 
       onInitialized: (app): void => {
         isAppInitialized = true;
-        if (shouldCheckLinks)
-          app.pages.forEach((page) => checkLinks(page, app));
+        if (linksCheckEnabled)
+          app.pages.forEach((page) => linksCheck(page, app, isIgnoreLink));
       },
 
       onPrepared: (app): Promise<void> =>

packages/shared/src/shared/utils/helper.ts

@@ -10,7 +10,7 @@ export const isFunction = <T extends Function>(val: any): val is T =>
 export const isNumber = (val: any): val is number => typeof val === "number";
 export const isString = (val: unknown): val is string =>
   typeof val === "string";
-
+export const isRegExp = (val: unknown): val is RegExp => val instanceof RegExp;
 /* String helper */
 
 export const startsWith = (str: unknown, prefix: string): boolean =>