feat(core): Add siteConfig.markdown.hooks, deprecate siteConfig.onBrokenMarkdownLinks

packages/create-docusaurus/templates/classic-typescript/docusaurus.config.ts

@@ -26,7 +26,6 @@ const config: Config = {
   projectName: 'docusaurus', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you

packages/create-docusaurus/templates/classic/docusaurus.config.js

@@ -31,7 +31,6 @@ const config = {
   projectName: 'docusaurus', // Usually your repo name.
 
   onBrokenLinks: 'throw',
-  onBrokenMarkdownLinks: 'warn',
 
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you

packages/docusaurus-mdx-loader/src/processor.ts

@@ -22,6 +22,9 @@ import type {WebpackCompilerName} from '@docusaurus/utils';
 import type {MDXFrontMatter} from './frontMatter';
 import type {Options} from './options';
 import type {AdmonitionOptions} from './remark/admonitions';
+import type {PluginOptions as ResolveMarkdownLinksOptions} from './remark/resolveMarkdownLinks';
+import type {PluginOptions as TransformLinksOptions} from './remark/transformLinks';
+import type {PluginOptions as TransformImageOptions} from './remark/transformImage';
 import type {ProcessorOptions} from '@mdx-js/mdx';
 
 // TODO as of April 2023, no way to import/re-export this ESM type easily :/
@@ -121,21 +124,29 @@ async function createProcessorFactory() {
         {
           staticDirs: options.staticDirs,
           siteDir: options.siteDir,
-        },
+          onBrokenMarkdownImages:
+            options.markdownConfig.hooks.onBrokenMarkdownImages,
+        } satisfies TransformImageOptions,
       ],
       // TODO merge this with transformLinks?
       options.resolveMarkdownLink
         ? [
             resolveMarkdownLinks,
-            {resolveMarkdownLink: options.resolveMarkdownLink},
+            {
+              resolveMarkdownLink: options.resolveMarkdownLink,
+              onBrokenMarkdownLinks:
+                options.markdownConfig.hooks.onBrokenMarkdownLinks,
+            } satisfies ResolveMarkdownLinksOptions,
           ]
         : undefined,
       [
         transformLinks,
         {
           staticDirs: options.staticDirs,
           siteDir: options.siteDir,
-        },
+          onBrokenMarkdownLinks:
+            options.markdownConfig.hooks.onBrokenMarkdownLinks,
+        } satisfies TransformLinksOptions,
       ],
       gfm,
       options.markdownConfig.mdx1Compat.comments ? comment : null,

packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/index.test.ts

@@ -5,22 +5,47 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {jest} from '@jest/globals';
+import * as path from 'path';
 import plugin from '..';
 import type {PluginOptions} from '../index';
 
-async function process(content: string) {
-  const {remark} = await import('remark');
+const siteDir = __dirname;
+
+const DefaultTestOptions: PluginOptions = {
+  resolveMarkdownLink: ({linkPathname}) => `/RESOLVED---${linkPathname}`,
+  onBrokenMarkdownLinks: 'throw',
+};
 
-  const options: PluginOptions = {
-    resolveMarkdownLink: ({linkPathname}) => `/RESOLVED---${linkPathname}`,
+async function process(content: string, optionsInput?: Partial<PluginOptions>) {
+  const options = {
+    ...DefaultTestOptions,
+    ...optionsInput,
   };
 
-  const result = await remark().use(plugin, options).process(content);
+  const {remark} = await import('remark');
+
+  const result = await remark()
+    .use(plugin, options)
+    .process({
+      value: content,
+      path: path.posix.join(siteDir, 'docs', 'myFile.mdx'),
+    });
 
   return result.value;
 }
 
 describe('resolveMarkdownLinks remark plugin', () => {
+  it('accepts non-md link', async () => {
+    /* language=markdown */
+    const content = `[link1](link1)`;
+    const result = await process(content);
+    expect(result).toMatchInlineSnapshot(`
+        "[link1](link1)
+        "
+      `);
+  });
+
   it('resolves Markdown and MDX links', async () => {
     /* language=markdown */
     const content = `[link1](link1.mdx)
@@ -157,4 +182,212 @@ this is a code block
       "
     `);
   });
+
+  describe('onBrokenMarkdownLinks', () => {
+    const warnMock = jest.spyOn(console, 'warn').mockImplementation(() => {});
+    beforeEach(() => {
+      warnMock.mockClear();
+    });
+
+    async function processResolutionErrors(
+      content: string,
+      onBrokenMarkdownLinks: PluginOptions['onBrokenMarkdownLinks'] = 'throw',
+    ) {
+      return process(content, {
+        resolveMarkdownLink: () => null,
+        onBrokenMarkdownLinks,
+      });
+    }
+
+    describe('throws', () => {
+      it('for unresolvable mdx link', async () => {
+        /* language=markdown */
+        const content = `[link1](link1.mdx)`;
+
+        await expect(() => processResolutionErrors(content)).rejects
+          .toThrowErrorMatchingInlineSnapshot(`
+          "Markdown link with URL \`link1.mdx\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (1:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.
+          To ignore this error, use the \`siteConfig.markdown.hooks.onBrokenMarkdownLinks\` option, or apply the \`pathname://\` protocol to the broken link URLs."
+        `);
+      });
+
+      it('for unresolvable md link', async () => {
+        /* language=markdown */
+        const content = `[link1](link1.md)`;
+
+        await expect(() => processResolutionErrors(content)).rejects
+          .toThrowErrorMatchingInlineSnapshot(`
+          "Markdown link with URL \`link1.md\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (1:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.
+          To ignore this error, use the \`siteConfig.markdown.hooks.onBrokenMarkdownLinks\` option, or apply the \`pathname://\` protocol to the broken link URLs."
+        `);
+      });
+    });
+
+    describe('warns', () => {
+      it('for unresolvable md and mdx link', async () => {
+        /* language=markdown */
+        const content = `
+[link1](link1.mdx)
+
+[link2](link2)
+
+[link3](dir/link3.md)
+
+[link 4](/link/4)
+      `;
+
+        const result = await processResolutionErrors(content, 'warn');
+
+        expect(result).toMatchInlineSnapshot(`
+                  "[link1](link1.mdx)
+
+                  [link2](link2)
+
+                  [link3](dir/link3.md)
+
+                  [link 4](/link/4)
+                  "
+              `);
+
+        expect(warnMock).toHaveBeenCalledTimes(2);
+        expect(warnMock.mock.calls).toMatchInlineSnapshot(`
+          [
+            [
+              "[WARNING] Markdown link with URL \`link1.mdx\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (2:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.",
+            ],
+            [
+              "[WARNING] Markdown link with URL \`dir/link3.md\` in source file "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx" (6:1) couldn't be resolved.
+          Make sure it references a local Markdown file that exists within the current plugin.",
+            ],
+          ]
+        `);
+      });
+
+      it('for unresolvable md and mdx link - with recovery', async () => {
+        /* language=markdown */
+        const content = `
+[link1](link1.mdx)
+
+[link2](link2)
+
+[link3](dir/link3.md?query#hash)
+
+[link 4](/link/4)
+      `;
+
+        const result = await processResolutionErrors(content, (params) => {
+          console.warn(`onBrokenMarkdownLinks called with`, params);
+          // We can alter the AST Node
+          params.node.title = 'fixed link title';
+          params.node.url = 'ignored, less important than returned value';
+          // Or return a new URL
+          return `/recovered-link`;
+        });
+
+        expect(result).toMatchInlineSnapshot(`
+          "[link1](/recovered-link "fixed link title")
+
+          [link2](link2)
+
+          [link3](/recovered-link "fixed link title")
+
+          [link 4](/link/4)
+          "
+        `);
+
+        expect(warnMock).toHaveBeenCalledTimes(2);
+        expect(warnMock.mock.calls).toMatchInlineSnapshot(`
+          [
+            [
+              "onBrokenMarkdownLinks called with",
+              {
+                "node": {
+                  "children": [
+                    {
+                      "position": {
+                        "end": {
+                          "column": 7,
+                          "line": 2,
+                          "offset": 7,
+                        },
+                        "start": {
+                          "column": 2,
+                          "line": 2,
+                          "offset": 2,
+                        },
+                      },
+                      "type": "text",
+                      "value": "link1",
+                    },
+                  ],
+                  "position": {
+                    "end": {
+                      "column": 19,
+                      "line": 2,
+                      "offset": 19,
+                    },
+                    "start": {
+                      "column": 1,
+                      "line": 2,
+                      "offset": 1,
+                    },
+                  },
+                  "title": "fixed link title",
+                  "type": "link",
+                  "url": "/recovered-link",
+                },
+                "sourceFilePath": "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx",
+                "url": "link1.mdx",
+              },
+            ],
+            [
+              "onBrokenMarkdownLinks called with",
+              {
+                "node": {
+                  "children": [
+                    {
+                      "position": {
+                        "end": {
+                          "column": 7,
+                          "line": 6,
+                          "offset": 43,
+                        },
+                        "start": {
+                          "column": 2,
+                          "line": 6,
+                          "offset": 38,
+                        },
+                      },
+                      "type": "text",
+                      "value": "link3",
+                    },
+                  ],
+                  "position": {
+                    "end": {
+                      "column": 33,
+                      "line": 6,
+                      "offset": 69,
+                    },
+                    "start": {
+                      "column": 1,
+                      "line": 6,
+                      "offset": 37,
+                    },
+                  },
+                  "title": "fixed link title",
+                  "type": "link",
+                  "url": "/recovered-link",
+                },
+                "sourceFilePath": "packages/docusaurus-mdx-loader/src/remark/resolveMarkdownLinks/__tests__/docs/myFile.mdx",
+                "url": "dir/link3.md?query#hash",
+              },
+            ],
+          ]
+        `);
+      });
+    });
+  });
 });