refactor(v2): docs plugin refactor (#3245)

* safe refactorings

* safe refactors

* add code to read versions more generically

* refactor docs plugin

* refactors

* stable docs refactor

* progress on refactor

* stable docs refactor

* stable docs refactor

* stable docs refactor

* attempt to fix admonition :(

* configureWebpack docs: better typing

* more refactors

* rename cli

* refactor docs metadata processing => move to pure function

* stable docs refactor

* stable docs refactor

* named exports

* basic sidebars refactor

* add getElementsAround utils

* refactor sidebar + ordering/navigation logic

* stable retrocompatible refactor

* add proper versions metadata tests

* fix docs metadata tests

* fix docs tests

* fix test due to absolute path

* fix webpack tests

* refactor linkify + add broken markdown links warning

* fix DOM warning due to forwarding legacy prop to div element

* add todo

packages/docusaurus-plugin-content-docs/src/markdown/__tests__/__fixtures__/docs/doc5.md

@@ -0,0 +1,6 @@
+### Not Existing Docs
+
+- [docNotExist1](docNotExist1.md)
+- [docNotExist2](./docNotExist2.mdx)
+- [docNotExist3](../docNotExist3.mdx)
+- [docNotExist4](./subdir/docNotExist4.md)

packages/docusaurus-plugin-content-docs/src/markdown/__tests__/linkify.test.ts

@@ -7,13 +7,41 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import linkify from '../linkify';
-import {SourceToPermalink} from '../../types';
-import {VERSIONED_DOCS_DIR} from '../../constants';
+import {linkify} from '../linkify';
+import {
+  DocsMarkdownOption,
+  SourceToPermalink,
+  VersionMetadata,
+  BrokenMarkdownLink,
+} from '../../types';
+import {VERSIONED_DOCS_DIR, CURRENT_VERSION_NAME} from '../../constants';
+
+function createFakeVersion(
+  versionName: string,
+  docsDirPath: string,
+): VersionMetadata {
+  return {
+    versionName,
+    versionLabel: 'Any',
+    versionPath: 'any',
+    docsDirPath,
+    sidebarFilePath: 'any',
+    routePriority: undefined,
+    isLast: false,
+  };
+}
 
 const siteDir = path.join(__dirname, '__fixtures__');
-const docsDir = path.join(siteDir, 'docs');
-const versionedDir = path.join(siteDir, VERSIONED_DOCS_DIR);
+
+const versionCurrent = createFakeVersion(
+  CURRENT_VERSION_NAME,
+  path.join(siteDir, 'docs'),
+);
+const version100 = createFakeVersion(
+  CURRENT_VERSION_NAME,
+  path.join(siteDir, VERSIONED_DOCS_DIR, 'version-1.0.0'),
+);
+
 const sourceToPermalink: SourceToPermalink = {
   '@site/docs/doc1.md': '/docs/doc1',
   '@site/docs/doc2.md': '/docs/doc2',
@@ -24,28 +52,34 @@ const sourceToPermalink: SourceToPermalink = {
     '/docs/1.0.0/subdir/doc1',
 };
 
-const transform = (filepath) => {
-  const content = fs.readFileSync(filepath, 'utf-8');
-  const transformedContent = linkify(
-    content,
-    filepath,
-    docsDir,
-    siteDir,
+function createMarkdownOptions(
+  options?: Partial<DocsMarkdownOption>,
+): DocsMarkdownOption {
+  return {
     sourceToPermalink,
-    versionedDir,
-  );
+    onBrokenMarkdownLink: () => {},
+    versionsMetadata: [versionCurrent, version100],
+    siteDir,
+    ...options,
+  };
+}
+
+const transform = (filepath: string, options?: Partial<DocsMarkdownOption>) => {
+  const markdownOptions = createMarkdownOptions(options);
+  const content = fs.readFileSync(filepath, 'utf-8');
+  const transformedContent = linkify(content, filepath, markdownOptions);
   return [content, transformedContent];
 };
 
 test('transform nothing', () => {
-  const doc1 = path.join(docsDir, 'doc1.md');
+  const doc1 = path.join(versionCurrent.docsDirPath, 'doc1.md');
   const [content, transformedContent] = transform(doc1);
   expect(transformedContent).toMatchSnapshot();
   expect(content).toEqual(transformedContent);
 });
 
 test('transform to correct links', () => {
-  const doc2 = path.join(docsDir, 'doc2.md');
+  const doc2 = path.join(versionCurrent.docsDirPath, 'doc2.md');
   const [content, transformedContent] = transform(doc2);
   expect(transformedContent).toMatchSnapshot();
   expect(transformedContent).toContain('](/docs/doc1');
@@ -58,7 +92,8 @@ test('transform to correct links', () => {
 });
 
 test('transform relative links', () => {
-  const doc3 = path.join(docsDir, 'subdir', 'doc3.md');
+  const doc3 = path.join(versionCurrent.docsDirPath, 'subdir', 'doc3.md');
+
   const [content, transformedContent] = transform(doc3);
   expect(transformedContent).toMatchSnapshot();
   expect(transformedContent).toContain('](/docs/doc2');
@@ -67,7 +102,7 @@ test('transform relative links', () => {
 });
 
 test('transforms reference links', () => {
-  const doc4 = path.join(docsDir, 'doc4.md');
+  const doc4 = path.join(versionCurrent.docsDirPath, 'doc4.md');
   const [content, transformedContent] = transform(doc4);
   expect(transformedContent).toMatchSnapshot();
   expect(transformedContent).toContain('[doc1]: /docs/doc1');
@@ -77,8 +112,38 @@ test('transforms reference links', () => {
   expect(content).not.toEqual(transformedContent);
 });
 
+test('report broken markdown links', () => {
+  const doc5 = path.join(versionCurrent.docsDirPath, 'doc5.md');
+  const onBrokenMarkdownLink = jest.fn();
+  const [content, transformedContent] = transform(doc5, {
+    onBrokenMarkdownLink,
+  });
+  expect(transformedContent).toEqual(content);
+  expect(onBrokenMarkdownLink).toHaveBeenCalledTimes(4);
+  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(1, {
+    filePath: doc5,
+    link: 'docNotExist1.md',
+    version: versionCurrent,
+  } as BrokenMarkdownLink);
+  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(2, {
+    filePath: doc5,
+    link: './docNotExist2.mdx',
+    version: versionCurrent,
+  } as BrokenMarkdownLink);
+  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(3, {
+    filePath: doc5,
+    link: '../docNotExist3.mdx',
+    version: versionCurrent,
+  } as BrokenMarkdownLink);
+  expect(onBrokenMarkdownLink).toHaveBeenNthCalledWith(4, {
+    filePath: doc5,
+    link: './subdir/docNotExist4.md',
+    version: versionCurrent,
+  } as BrokenMarkdownLink);
+});
+
 test('transforms absolute links in versioned docs', () => {
-  const doc2 = path.join(versionedDir, 'version-1.0.0', 'doc2.md');
+  const doc2 = path.join(version100.docsDirPath, 'doc2.md');
   const [content, transformedContent] = transform(doc2);
   expect(transformedContent).toMatchSnapshot();
   expect(transformedContent).toContain('](/docs/1.0.0/subdir/doc1');
@@ -89,7 +154,7 @@ test('transforms absolute links in versioned docs', () => {
 });
 
 test('transforms relative links in versioned docs', () => {
-  const doc1 = path.join(versionedDir, 'version-1.0.0', 'subdir', 'doc1.md');
+  const doc1 = path.join(version100.docsDirPath, 'subdir', 'doc1.md');
   const [content, transformedContent] = transform(doc1);
   expect(transformedContent).toMatchSnapshot();
   expect(transformedContent).toContain('](/docs/1.0.0/doc2');

packages/docusaurus-plugin-content-docs/src/markdown/index.ts

@@ -7,26 +7,15 @@
 
 import {getOptions} from 'loader-utils';
 import {loader} from 'webpack';
-import linkify from './linkify';
+import {linkify} from './linkify';
+import {DocsMarkdownOption} from '../types';
 
 const markdownLoader: loader.Loader = function (source) {
   const fileString = source as string;
   const callback = this.async();
-  const {docsDir, siteDir, versionedDir, sourceToPermalink} = getOptions(this);
-
+  const options = getOptions(this) as DocsMarkdownOption;
   return (
-    callback &&
-    callback(
-      null,
-      linkify(
-        fileString,
-        this.resourcePath,
-        docsDir,
-        siteDir,
-        sourceToPermalink,
-        versionedDir,
-      ),
-    )
+    callback && callback(null, linkify(fileString, this.resourcePath, options))
   );
 };
 

packages/docusaurus-plugin-content-docs/src/markdown/linkify.ts

@@ -7,68 +7,81 @@
 
 import path from 'path';
 import {resolve} from 'url';
-import {getSubFolder} from '@docusaurus/utils';
-import {SourceToPermalink} from '../types';
+import {
+  DocsMarkdownOption,
+  VersionMetadata,
+  BrokenMarkdownLink,
+} from '../types';
 
-export default function (
+function getVersion(filePath: string, options: DocsMarkdownOption) {
+  const versionFound = options.versionsMetadata.find((version) =>
+    filePath.startsWith(version.docsDirPath),
+  );
+  if (!versionFound) {
+    throw new Error(
+      `Unexpected, markdown file does not belong to any docs version! file=${filePath}`,
+    );
+  }
+  return versionFound;
+}
+
+function replaceMarkdownLinks(
   fileString: string,
   filePath: string,
-  docsDir: string,
-  siteDir: string,
-  sourceToPermalink: SourceToPermalink,
-  versionedDir?: string,
-): string {
-  // Determine the source dir. e.g: /website/docs, /website/versioned_docs/version-1.0.0
-  let sourceDir: string | undefined;
-  const thisSource = filePath;
-  if (thisSource.startsWith(docsDir)) {
-    sourceDir = docsDir;
-  } else if (versionedDir && thisSource.startsWith(versionedDir)) {
-    const specificVersionDir = getSubFolder(thisSource, versionedDir);
-    // e.g: specificVersionDir = version-1.0.0
-    if (specificVersionDir) {
-      sourceDir = path.join(versionedDir, specificVersionDir);
-    }
-  }
-
-  let content = fileString;
+  version: VersionMetadata,
+  options: DocsMarkdownOption,
+) {
+  const {siteDir, sourceToPermalink, onBrokenMarkdownLink} = options;
+  const {docsDirPath} = version;
 
   // Replace internal markdown linking (except in fenced blocks).
-  if (sourceDir) {
-    let fencedBlock = false;
-    const lines = content.split('\n').map((line) => {
-      if (line.trim().startsWith('```')) {
-        fencedBlock = !fencedBlock;
-      }
-      if (fencedBlock) {
-        return line;
-      }
+  let fencedBlock = false;
+  const lines = fileString.split('\n').map((line) => {
+    if (line.trim().startsWith('```')) {
+      fencedBlock = !fencedBlock;
+    }
+    if (fencedBlock) {
+      return line;
+    }
 
-      let modifiedLine = line;
-      // Replace inline-style links or reference-style links e.g:
-      // This is [Document 1](doc1.md) -> we replace this doc1.md with correct link
-      // [doc1]: doc1.md -> we replace this doc1.md with correct link
-      const mdRegex = /(?:(?:\]\()|(?:\]:\s?))(?!https)([^'")\]\s>]+\.mdx?)/g;
-      let mdMatch = mdRegex.exec(modifiedLine);
-      while (mdMatch !== null) {
-        // Replace it to correct html link.
-        const mdLink = mdMatch[1];
-        const targetSource = `${sourceDir}/${mdLink}`;
-        const aliasedSource = (source: string) =>
-          `@site/${path.relative(siteDir, source)}`;
-        const permalink =
-          sourceToPermalink[aliasedSource(resolve(thisSource, mdLink))] ||
-          sourceToPermalink[aliasedSource(targetSource)];
-        if (permalink) {
-          modifiedLine = modifiedLine.replace(mdLink, permalink);
-        }
-        mdMatch = mdRegex.exec(modifiedLine);
+    let modifiedLine = line;
+    // Replace inline-style links or reference-style links e.g:
+    // This is [Document 1](doc1.md) -> we replace this doc1.md with correct link
+    // [doc1]: doc1.md -> we replace this doc1.md with correct link
+    const mdRegex = /(?:(?:\]\()|(?:\]:\s?))(?!https)([^'")\]\s>]+\.mdx?)/g;
+    let mdMatch = mdRegex.exec(modifiedLine);
+    while (mdMatch !== null) {
+      // Replace it to correct html link.
+      const mdLink = mdMatch[1];
+      const targetSource = `${docsDirPath}/${mdLink}`;
+      const aliasedSource = (source: string) =>
+        `@site/${path.relative(siteDir, source)}`;
+      const permalink =
+        sourceToPermalink[aliasedSource(resolve(filePath, mdLink))] ||
+        sourceToPermalink[aliasedSource(targetSource)];
+      if (permalink) {
+        modifiedLine = modifiedLine.replace(mdLink, permalink);
+      } else {
+        const brokenMarkdownLink: BrokenMarkdownLink = {
+          version,
+          filePath,
+          link: mdLink,
+        };
+        onBrokenMarkdownLink(brokenMarkdownLink);
       }
-      return modifiedLine;
-    });
+      mdMatch = mdRegex.exec(modifiedLine);
+    }
+    return modifiedLine;
+  });
 
-    content = lines.join('\n');
-  }
-
-  return content;
+  return lines.join('\n');
+}
+
+export function linkify(
+  fileString: string,
+  filePath: string,
+  options: DocsMarkdownOption,
+): string {
+  const version = getVersion(filePath, options);
+  return replaceMarkdownLinks(fileString, filePath, version, options);
 }