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
2025-05-20 12:37:01 +02:00 · 2020-08-17 17:50:22 +02:00 · 2020-08-17 17:50:22 +02:00 · a4c8a7f55b
commit a4c8a7f55b
parent d17df954b5
54 changed files with 3219 additions and 2724 deletions
--- a/packages/docusaurus-plugin-content-docs/src/markdown/linkify.ts
+++ b/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);
 }