@docusaurus/utils 3.10.2 → 4.0.0-canary-6808

package/src/markdownUtils.ts

@@ -7,6 +7,7 @@
 
 import logger from '@docusaurus/logger';
 import matter from '@11ty/gray-matter';
+
 import type {
   ParseFrontMatter,
   DefaultParseFrontMatter,
@@ -16,6 +17,41 @@ import type {
 // server-side when we infer metadata like `title` and `description` from the
 // content. Most parsing is still done in MDX through the mdx-loader.
 
+const MDXEscapingUtils = (function () {
+  const MARKUP_CHARS = ['_', ':', '*', '<', '>', '~', '!', '[', ']', '{', '}'];
+
+  const markerOf = (char: string) => `\u{FFFE}${char.codePointAt(0)}\u{FFFF}`;
+
+  const MARKUP_CHARS_ESCAPE_MAP = new Map(
+    MARKUP_CHARS.map((char) => [char, markerOf(char)]),
+  );
+  const MARKUP_CHARS_UNESCAPE_MAP = new Map(
+    MARKUP_CHARS.map((char) => [markerOf(char), char]),
+  );
+
+  const MARKUP_CHARS_REGEX = new RegExp(
+    `[${RegExp.escape(MARKUP_CHARS.join(''))}]`,
+    'g',
+  );
+  const MARKUP_MARKERS_REGEX = /\u{FFFE}\d+\u{FFFF}/gu;
+
+  function escapeMDX(str: string) {
+    return str.replace(
+      MARKUP_CHARS_REGEX,
+      (char) => MARKUP_CHARS_ESCAPE_MAP.get(char)!,
+    );
+  }
+
+  function unescapeMDX(str: string) {
+    return str.replace(
+      MARKUP_MARKERS_REGEX,
+      (marker) => MARKUP_CHARS_UNESCAPE_MAP.get(marker) ?? marker,
+    );
+  }
+
+  return {escapeMDX, unescapeMDX};
+})();
+
 /**
  * Hacky temporary escape hatch for Crowdin bad MDX support
  * See https://docusaurus.io/docs/i18n/crowdin#mdx
@@ -92,6 +128,7 @@ export function createExcerpt(fileString: string): string | undefined {
     .split(/\r?\n/);
   let inCode = false;
   let inImport = false;
+  let inHTML = false;
   let lastCodeFence = '';
 
   for (const fileLine of fileLines) {
@@ -127,11 +164,44 @@ export function createExcerpt(fileString: string): string | undefined {
       continue;
     }
 
-    const cleanedLine = fileLine
+    // Skip lines inside a multi-line JSX/HTML element. An opening "<Tag ..."
+    // with no ">" on the same line would otherwise leak into the excerpt
+    // (e.g. "<MyComponent"). Skip until the element's tag closes.
+    if (inHTML) {
+      if (fileLine.includes('>')) {
+        inHTML = false;
+      }
+      continue;
+    }
+    if (/^\s*<[a-z][^>]*$/i.test(fileLine)) {
+      inHTML = true;
+      continue;
+    }
+
+    // Pre/postprocessing to handle MDX special chars within inline code blocks
+    // See https://github.com/facebook/docusaurus/pull/11821
+    function preprocessLine(str: string) {
+      return (
+        str
+          // Ignore internal Unicode markers found in input
+          // This ensures no possible conflict with our MDX escaping logic
+          .replace(/[\u{FFFE}\u{FFFF}]/gu, '')
+          // Unwrap inline code and escape special MDX chars within it
+          .replace(/`(?<text>.+?)`/g, (_, text) => {
+            return MDXEscapingUtils.escapeMDX(text);
+          })
+      );
+    }
+    function postProcessLine(str: string) {
+      // Restore escaped MDX chars that have been previously escaped
+      return MDXEscapingUtils.unescapeMDX(str);
+    }
+
+    const cleanedLine = preprocessLine(fileLine)
       // Remove HTML tags.
       .replace(/<[^>]*>/g, '')
       // Remove Title headers
-      .replace(/^#[^#]+#?/gm, '')
+      .replace(/^#(?!#).*/gm, '')
       // Remove Markdown + ATX-style headers
       .replace(/^#{1,6}\s*(?<text>[^#]*?)\s*#{0,6}/gm, '$1')
       // Remove emphasis.
@@ -144,8 +214,6 @@ export function createExcerpt(fileString: string): string | undefined {
       .replace(/\[\^.+?\](?:: .*$)?/g, '')
       // Remove inline links.
       .replace(/\[(?<alt>.*?)\][[(].*?[\])]/g, '$1')
-      // Remove inline code.
-      .replace(/`(?<text>.+?)`/g, '$1')
       // Remove blockquotes.
       .replace(/^\s{0,3}>\s?/g, '')
       // Remove admonition definition.
@@ -154,10 +222,12 @@ export function createExcerpt(fileString: string): string | undefined {
       .replace(/\s?:(?:::|[^:\n])+:/g, '')
       // Remove custom Markdown heading id.
       .replace(/\{#*[\w-]+\}/, '')
+      // Collapse whitespace left behind by the removals above.
+      .replace(/\s+/g, ' ')
       .trim();
 
     if (cleanedLine) {
-      return cleanedLine;
+      return postProcessLine(cleanedLine);
     }
   }
 
@@ -191,14 +261,7 @@ export function parseFileContentFrontMatter(fileContent: string): {
   // Unfortunately, this becomes a problem when we mutate returned front matter
   // We want to make it possible as part of the parseFrontMatter API
   // So we make it safe to mutate by always providing a deep copy
-  const frontMatter =
-    // And of course structuredClone() doesn't work well with Date in Jest...
-    // See https://github.com/jestjs/jest/issues/2549
-    // So we parse again for tests with a {} option object
-    // This undocumented empty option object disables gray-matter caching..
-    process.env.JEST_WORKER_ID
-      ? matter(fileContent, {}).data
-      : structuredClone(data);
+  const frontMatter = structuredClone(data);
 
   return {
     frontMatter,
@@ -247,18 +310,18 @@ export function parseMarkdownContentTitle(
   const removeContentTitleOption = options?.removeContentTitle ?? false;
 
   const content = contentUntrimmed.trim();
-  // We only need to detect import statements that will be parsed by MDX as
-  // `import` nodes, as broken syntax can't render anyways. That means any block
-  // that has `import` at the very beginning and surrounded by empty lines.
-  const contentWithoutImport = content
-    .replace(/^(?:import\s(?:.|\r?\n(?!\r?\n))*(?:\r?\n){2,})*/, '')
+  // We only need to detect import/export statements that will be parsed by MDX as
+  // `import` or `export` nodes, as broken syntax can't render anyways. That means any block
+  // that has `import` or `export` at the very beginning and surrounded by empty lines.
+  const contentWithoutImportExport = content
+    .replace(/^(?:(?:import|export)\s(?:.|\r?\n(?!\r?\n))*(?:\r?\n){2,})*/, '')
     .trim();
 
   const regularTitleMatch = /^#[ \t]+(?<title>[^ \t].*)(?:\r?\n|$)/.exec(
-    contentWithoutImport,
+    contentWithoutImportExport,
   );
   const alternateTitleMatch = /^(?<title>.*)\r?\n=+(?:\r?\n|$)/.exec(
-    contentWithoutImport,
+    contentWithoutImportExport,
   );
 
   const titleMatch = regularTitleMatch ?? alternateTitleMatch;

package/src/moduleUtils.ts

@@ -5,33 +5,54 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import jiti from 'jiti';
 import logger from '@docusaurus/logger';
+import {createJiti} from 'jiti';
+
+const DEBUG = false;
+
+const jiti = createJiti(__filename, {
+  // Transpilation cache, can be safely enabled
+  fsCache: true,
+  // Bypass Node.js runtime require cache for hot reloads
+  moduleCache: false,
+
+  interopDefault: true,
+  debug: DEBUG,
+});
 
 /*
 jiti is able to load ESM, CJS, JSON, TS modules
  */
-export async function loadFreshModule(modulePath: string): Promise<unknown> {
+export async function loadFreshModule(
+  modulePath: string,
+  options?: {
+    default?: true; // Use this when only the default export matters
+  },
+): Promise<unknown> {
   if (typeof modulePath !== 'string') {
     throw new Error(
       logger.interpolate`Invalid module path of type "name=${typeof modulePath}" with value "name=${modulePath}"`,
     );
   }
   try {
-    const load = jiti(__filename, {
-      // Transpilation cache, can be safely enabled
-      cache: true,
-      // Bypass Node.js runtime require cache
-      // Same as "import-fresh" package we used previously
-      requireCache: false,
-      // Only take into consideration the default export
-      // For now we don't need named exports
-      // This also helps normalize return value for both CJS/ESM/TS modules
-      interopDefault: true,
-      // debug: true,
+    const module = await jiti.import(modulePath, {
+      default: options?.default,
     });
 
-    return load(modulePath);
+    if (DEBUG) {
+      console.log('Jiti module loaded', {
+        modulePath,
+        options,
+        type: typeof module,
+        keys:
+          module && typeof module === 'object'
+            ? Object.keys(module)
+            : undefined,
+        module,
+      });
+    }
+
+    return module;
   } catch (error) {
     throw new Error(
       logger.interpolate`Docusaurus could not load module at path path=${modulePath}`,

package/src/urlUtils.ts

@@ -138,8 +138,8 @@ export function fileToPath(file: string): string {
  * Similar to `encodeURI`, but uses `encodeURIComponent` and assumes there's no
  * query.
  *
- * `encodeURI("/question?/answer")` => `"/question?/answer#section"`;
- * `encodePath("/question?/answer#section")` => `"/question%3F/answer%23foo"`
+ * `encodeURI("/question?/answer")` => `"/question?/answer"`;
+ * `encodePath("/question?/answer#section")` => `"/question%3F/answer%23section"`
  */
 export function encodePath(userPath: string): string {
   return userPath
@@ -156,26 +156,20 @@ export function isValidPathname(str: string): boolean {
   if (!str.startsWith('/')) {
     return false;
   }
-  try {
-    const parsedPathname = new URL(str, 'https://domain.com').pathname;
-    return parsedPathname === str || parsedPathname === encodeURI(str);
-  } catch {
+  const url = URL.parse(str, 'https://domain.com');
+  if (url === null) {
     return false;
   }
+  const parsedPathname = url.pathname;
+  return parsedPathname === str || parsedPathname === encodeURI(str);
 }
 
-export function parseURLOrPath(url: string, base?: string | URL): URL {
-  try {
-    // TODO Docusaurus v4: use URL.parse()
-    //  Node 24 supports it, use URL.parse could be faster?
-    //  see https://kilianvalkhof.com/2024/javascript/the-problem-with-new-url-and-how-url-parse-fixes-that/
-    return new URL(url, base ?? 'https://example.com');
-  } catch (e) {
-    throw new Error(
-      `Can't parse URL ${url}${base ? ` with base ${base}` : ''}`,
-      {cause: e},
-    );
+export function parseURLOrPath(str: string, base?: string | URL): URL {
+  const url = URL.parse(str, base ?? 'https://example.com');
+  if (url) {
+    return url;
   }
+  throw new Error(`Can't parse URL ${str}${base ? ` with base ${base}` : ''}`);
 }
 
 export type URLPath = {pathname: string; search?: string; hash?: string};
@@ -183,15 +177,19 @@ export type URLPath = {pathname: string; search?: string; hash?: string};
 export function toURLPath(url: URL): URLPath {
   const {pathname} = url;
 
+  // Only the part before the fragment can contain the query string. A "?"
+  // inside the hash (e.g. "/foo#bar?baz") must not be read as an empty query.
+  const beforeHash = url.hash ? url.href.slice(0, -url.hash.length) : url.href;
+
   // Fixes annoying url.search behavior
   // "" => undefined
   // "?" => ""
   // "?param => "param"
   const search = url.search
     ? url.search.slice(1)
-    : url.href.includes('?')
-    ? ''
-    : undefined;
+    : beforeHash.includes('?')
+      ? ''
+      : undefined;
 
   // Fixes annoying url.hash behavior
   // "" => undefined
@@ -200,8 +198,8 @@ export function toURLPath(url: URL): URLPath {
   const hash = url.hash
     ? url.hash.slice(1)
     : url.href.includes('#')
-    ? ''
-    : undefined;
+      ? ''
+      : undefined;
 
   return {
     pathname,
@@ -319,13 +317,11 @@ export function buildHttpsUrl(
  * `git@github.com:facebook/docusaurus.git`.
  */
 export function hasSSHProtocol(sourceRepoUrl: string): boolean {
-  try {
-    if (new URL(sourceRepoUrl).protocol === 'ssh:') {
-      return true;
-    }
-    return false;
-  } catch {
-    // Fails when there isn't a protocol
+  const url = URL.parse(sourceRepoUrl);
+  if (url === null) {
+    // Recognizes SCP-style addresses, implying SSH
+    // Example: git@github.com:facebook/docusaurus.git
     return /^(?:[\w-]+@)?[\w.-]+:[\w./-]+/.test(sourceRepoUrl);
   }
+  return url.protocol === 'ssh:';
 }

package/src/vcs/gitUtils.ts

@@ -9,17 +9,13 @@ import path from 'path';
 import fs from 'fs-extra';
 import os from 'os';
 import _ from 'lodash';
-import execa from 'execa';
+import {execa, execaSync} from 'execa';
 import PQueue from 'p-queue';
 import logger from '@docusaurus/logger';
 
 // Quite high/conservative concurrency value (it was previously "Infinity")
 // See https://github.com/facebook/docusaurus/pull/10915
-const DefaultGitCommandConcurrency =
-  // TODO Docusaurus v4: bump node, availableParallelism() now always exists
-  (typeof os.availableParallelism === 'function'
-    ? os.availableParallelism()
-    : os.cpus().length) * 4;
+const DefaultGitCommandConcurrency = os.availableParallelism() * 4;
 
 const GitCommandConcurrencyEnv = process.env.DOCUSAURUS_GIT_COMMAND_CONCURRENCY
   ? parseInt(process.env.DOCUSAURUS_GIT_COMMAND_CONCURRENCY, 10)
@@ -38,8 +34,8 @@ const GitCommandQueue = new PQueue({
 
 const realHasGitFn = () => {
   try {
-    return execa.sync('git', ['--version']).exitCode === 0;
-  } catch (error) {
+    return execaSync('git', ['--version']).exitCode === 0;
+  } catch {
     return false;
   }
 };
@@ -147,32 +143,26 @@ export async function getFileCommitDate(
   // See why: https://github.com/facebook/docusaurus/pull/10022
   const resultFormat = includeAuthor ? 'RESULT:%ct,%an' : 'RESULT:%ct';
 
-  const args = [
-    `--format=${resultFormat}`,
-    '--max-count=1',
-    age === 'oldest' ? '--follow --diff-filter=A' : undefined,
-  ]
-    .filter(Boolean)
-    .join(' ');
-
-  // Do not include GPG signature in the log output
-  // See https://github.com/facebook/docusaurus/pull/10022
-  const command = `git -c log.showSignature=false log ${args} -- "${path.basename(
-    file,
-  )}"`;
-
   const result = (await GitCommandQueue.add(() => {
-    return execa(command, {
-      cwd: path.dirname(file),
-      shell: true,
-    });
-  }))!;
-
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `Failed to retrieve the git history for file "${file}" with exit code ${result.exitCode}: ${result.stderr}`,
+    return execa(
+      'git',
+      [
+        // Do not include GPG signature in the log output
+        // See https://github.com/facebook/docusaurus/pull/10022
+        '-c',
+        'log.showSignature=false',
+        'log',
+        `--format=${resultFormat}`,
+        '--max-count=1',
+        ...(age === 'oldest' ? ['--follow', '--diff-filter=A'] : []),
+        '--',
+        path.basename(file),
+      ],
+      {
+        cwd: path.dirname(file),
+      },
     );
-  }
+  }))!;
 
   // We only parse the output line starting with our "RESULT:" prefix
   // See why https://github.com/facebook/docusaurus/pull/10022
@@ -280,33 +270,20 @@ export async function isGitInsideWorktree(cwd: string): Promise<boolean> {
 }
 
 export async function getGitRepoRoot(cwd: string): Promise<string> {
-  const createErrorMessageBase = () => {
-    return `Couldn't find the git repository root directory
-Failure while running ${logger.code(
-      'git rev-parse --show-toplevel',
-    )} from cwd=${logger.path(cwd)}`;
-  };
-
   const result = await execa('git', ['rev-parse', '--show-toplevel'], {
     cwd,
   }).catch((error) => {
     // We enter this rejection when cwd is not a dir for example
     throw new Error(
-      `${createErrorMessageBase()}
+      `Couldn't find the git repository root directory
+Failure while running ${logger.code(
+        'git rev-parse --show-toplevel',
+      )} from cwd=${logger.path(cwd)}
 The command executed throws an error: ${error.message}`,
       {cause: error},
     );
   });
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `${createErrorMessageBase()}
-The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
-        result.stderr,
-      )}`,
-    );
-  }
-
   return fs.realpath.native(result.stdout.trim());
 }
 
@@ -316,13 +293,6 @@ The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
 export async function getGitSuperProjectRoot(
   cwd: string,
 ): Promise<string | null> {
-  const createErrorMessageBase = () => {
-    return `Couldn't find the git superproject root directory
-Failure while running ${logger.code(
-      'git rev-parse --show-superproject-working-tree',
-    )} from cwd=${logger.path(cwd)}`;
-  };
-
   const result = await execa(
     'git',
     ['rev-parse', '--show-superproject-working-tree'],
@@ -332,21 +302,15 @@ Failure while running ${logger.code(
   ).catch((error) => {
     // We enter this rejection when cwd is not a dir for example
     throw new Error(
-      `${createErrorMessageBase()}
+      `Couldn't find the git superproject root directory
+Failure while running ${logger.code(
+        'git rev-parse --show-superproject-working-tree',
+      )} from cwd=${logger.path(cwd)}
 The command executed throws an error: ${error.message}`,
       {cause: error},
     );
   });
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `${createErrorMessageBase()}
-The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
-        result.stderr,
-      )}`,
-    );
-  }
-
   const output = result.stdout.trim();
   // this command only works when inside submodules
   // otherwise it doesn't return anything when we are inside the main repo
@@ -358,33 +322,20 @@ The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
 
 // See https://git-scm.com/book/en/v2/Git-Tools-Submodules
 export async function getGitSubmodulePaths(cwd: string): Promise<string[]> {
-  const createErrorMessageBase = () => {
-    return `Couldn't read the list of git submodules
-Failure while running ${logger.code(
-      'git submodule status',
-    )} from cwd=${logger.path(cwd)}`;
-  };
-
   const result = await execa('git', ['submodule', 'status'], {
     cwd,
   }).catch((error) => {
     // We enter this rejection when cwd is not a dir for example
     throw new Error(
-      `${createErrorMessageBase()}
+      `Couldn't read the list of git submodules
+Failure while running ${logger.code(
+        'git submodule status',
+      )} from cwd=${logger.path(cwd)}
 The command executed throws an error: ${error.message}`,
       {cause: error},
     );
   });
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `${createErrorMessageBase()}
-The command returned exit code ${logger.code(result.exitCode)}: ${logger.subdue(
-        result.stderr,
-      )}`,
-    );
-  }
-
   const output = result.stdout.trim();
 
   if (!output) {
@@ -465,20 +416,12 @@ export async function getGitRepositoryFilesInfo(
     ],
     {
       cwd,
-      encoding: 'utf-8',
       // TODO use streaming to avoid a large buffer
       // See https://github.com/withastro/starlight/issues/3154
       maxBuffer: 20 * 1024 * 1024,
     },
   );
 
-  if (result.exitCode !== 0) {
-    throw new Error(
-      `Docusaurus failed to run the 'git log' to retrieve tracked files last update date/author.
-The command exited with code ${result.exitCode}: ${result.stderr}`,
-    );
-  }
-
   const logLines = result.stdout.split('\n');
 
   const now = Date.now();

package/src/vcs/vcsGitEager.ts

@@ -56,6 +56,7 @@ type InitializeResult =
   | {
       type: 'success';
       filesMap: GitFileInfoMap;
+      siteDir: string;
     }
   | {
       type: 'error';
@@ -74,7 +75,7 @@ async function initialize({
       return {type: 'error', reason: 'not-in-worktree'};
     }
     const filesMap = await loadAllGitFilesInfoMap(siteDir);
-    return {type: 'success', filesMap};
+    return {type: 'success', filesMap, siteDir};
   } catch (error) {
     return {type: 'error', reason: 'unknown', cause: error as Error};
   }
@@ -86,7 +87,8 @@ export function createVcsGitEagerConfig(): VcsConfig {
   async function getGitFileInfo(filePath: string): Promise<GitFileInfo | null> {
     const init = (await initPromise)!;
     if (init.type === 'success') {
-      return init.filesMap.get(filePath) ?? null;
+      const key = resolve(init.siteDir, filePath);
+      return init.filesMap.get(key) ?? null;
     } else if (init.reason === 'not-in-worktree') {
       throw new Error(
         `This Docusaurus site is outside any Git worktree.

package/src/webpackUtils.ts

@@ -18,7 +18,6 @@ export type WebpackCompilerName = 'server' | 'client';
 export function getWebpackLoaderCompilerName(
   context: LoaderContext<unknown>,
 ): WebpackCompilerName {
-  // eslint-disable-next-line no-underscore-dangle
   const compilerName = context._compiler?.name;
   switch (compilerName) {
     case 'server':

package/lib/regExpUtils.d.ts

@@ -1,8 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-export declare function escapeRegexp(string: string): string;
-//# sourceMappingURL=regExpUtils.d.ts.map

package/lib/regExpUtils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"regExpUtils.d.ts","sourceRoot":"","sources":["../src/regExpUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/lib/regExpUtils.js

@@ -1,15 +0,0 @@
-"use strict";
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.escapeRegexp = escapeRegexp;
-const tslib_1 = require("tslib");
-const escape_string_regexp_1 = tslib_1.__importDefault(require("escape-string-regexp"));
-function escapeRegexp(string) {
-    return (0, escape_string_regexp_1.default)(string);
-}
-//# sourceMappingURL=regExpUtils.js.map

package/lib/regExpUtils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"regExpUtils.js","sourceRoot":"","sources":["../src/regExpUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAIH,oCAEC;;AAJD,wFAAsD;AAEtD,SAAgB,YAAY,CAAC,MAAc;IACzC,OAAO,IAAA,8BAAkB,EAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/src/regExpUtils.ts

@@ -1,12 +0,0 @@
-/**
- * Copyright (c) Facebook, Inc. and its affiliates.
- *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
- */
-
-import escapeStringRegexp from 'escape-string-regexp';
-
-export function escapeRegexp(string: string): string {
-  return escapeStringRegexp(string);
-}