@docusaurus/utils 2.0.0-beta.15 → 2.0.0-beta.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/utils",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.16",
   "description": "Node utility functions for Docusaurus packages.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,40 +18,32 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/logger": "2.0.0-beta.15",
-    "@mdx-js/runtime": "^1.6.22",
+    "@docusaurus/logger": "2.0.0-beta.16",
     "@svgr/webpack": "^6.0.0",
     "file-loader": "^6.2.0",
-    "fs-extra": "^10.0.0",
+    "fs-extra": "^10.0.1",
     "github-slugger": "^1.4.0",
     "globby": "^11.0.4",
     "gray-matter": "^4.0.3",
-    "js-yaml": "^4.0.0",
-    "lodash": "^4.17.20",
+    "js-yaml": "^4.1.0",
+    "lodash": "^4.17.21",
     "micromatch": "^4.0.4",
-    "remark-mdx-remove-exports": "^1.6.22",
-    "remark-mdx-remove-imports": "^1.6.22",
     "resolve-pathname": "^3.0.0",
+    "shelljs": "^0.8.5",
     "tslib": "^2.3.1",
-    "url-loader": "^4.1.1"
+    "url-loader": "^4.1.1",
+    "webpack": "^5.69.1"
   },
   "engines": {
     "node": ">=14"
   },
   "devDependencies": {
-    "@docusaurus/types": "2.0.0-beta.15",
+    "@docusaurus/types": "2.0.0-beta.16",
     "@types/dedent": "^0.7.0",
     "@types/github-slugger": "^1.3.0",
     "@types/micromatch": "^4.0.2",
-    "@types/react-dom": "^17.0.1",
-    "dedent": "^0.7.0",
-    "tslib": "^2.3.1"
+    "@types/react-dom": "^17.0.11",
+    "dedent": "^0.7.0"
   },
-  "peerDependencies": {
-    "@babel/core": "^7.0.0",
-    "react": "*",
-    "react-dom": "*",
-    "webpack": "5.x"
-  },
-  "gitHead": "32ec84ef3c0a238436e913b2026ab809e5750fa8"
+  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
 }

package/src/dataFileUtils.ts

@@ -48,10 +48,10 @@ export async function getDataFileData<T>(
     const contentString = await fs.readFile(filePath, {encoding: 'utf8'});
     const unsafeContent = Yaml.load(contentString);
     return validate(unsafeContent);
-  } catch (e) {
+  } catch (err) {
     // TODO replace later by error cause, see https://v8.dev/features/error-cause
     logger.error`The ${params.fileType} file at path=${filePath} looks invalid.`;
-    throw e;
+    throw err;
   }
 }
 

package/src/deps.d.ts

@@ -8,7 +8,3 @@
 declare module 'resolve-pathname' {
   export default function resolvePathname(to: string, from?: string): string;
 }
-
-declare module '@mdx-js/runtime';
-declare module 'remark-mdx-remove-imports';
-declare module 'remark-mdx-remove-exports';

package/src/gitUtils.ts

@@ -0,0 +1,93 @@
+/**
+ * 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 path from 'path';
+import shell from 'shelljs';
+
+export class GitNotFoundError extends Error {}
+
+export const getFileCommitDate = (
+  file: string,
+  {
+    age = 'oldest',
+    includeAuthor = false,
+  }: {
+    age?: 'oldest' | 'newest';
+    includeAuthor?: boolean;
+  },
+): {
+  date: Date;
+  timestamp: number;
+  author?: string;
+} => {
+  if (!shell.which('git')) {
+    throw new GitNotFoundError(
+      `Failed to retrieve git history for "${file}" because git is not installed.`,
+    );
+  }
+
+  if (!shell.test('-f', file)) {
+    throw new Error(
+      `Failed to retrieve git history for "${file}" because the file does not exist.`,
+    );
+  }
+
+  const fileBasename = path.basename(file);
+  const fileDirname = path.dirname(file);
+
+  let formatArg = '--format=%ct';
+  if (includeAuthor) {
+    formatArg += ',%an';
+  }
+
+  let extraArgs = '--max-count=1';
+  if (age === 'oldest') {
+    // --follow is necessary to follow file renames
+    // --diff-filter=A ensures we only get the commit which (A)dded the file
+    extraArgs += ' --follow --diff-filter=A';
+  }
+
+  const result = shell.exec(
+    `git log ${extraArgs} ${formatArg} -- "${fileBasename}"`,
+    {
+      // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
+      cwd: fileDirname,
+      silent: true,
+    },
+  );
+  if (result.code !== 0) {
+    throw new Error(
+      `Failed to retrieve the git history for file "${file}" with exit code ${result.code}: ${result.stderr}`,
+    );
+  }
+  let regex = /^(?<timestamp>\d+)$/;
+  if (includeAuthor) {
+    regex = /^(?<timestamp>\d+),(?<author>.+)$/;
+  }
+
+  const output = result.stdout.trim();
+  const match = output.match(regex);
+
+  if (
+    !match ||
+    !match.groups ||
+    !match.groups.timestamp ||
+    (includeAuthor && !match.groups.author)
+  ) {
+    throw new Error(
+      `Failed to retrieve the git history for file "${file}" with unexpected output: ${output}`,
+    );
+  }
+
+  const timestamp = Number(match.groups.timestamp);
+  const date = new Date(timestamp * 1000);
+
+  if (includeAuthor) {
+    return {date, timestamp, author: match.groups.author};
+  }
+  return {date, timestamp};
+};

package/src/hashUtils.ts

@@ -6,7 +6,7 @@
  */
 
 import {createHash} from 'crypto';
-import {kebabCase} from 'lodash';
+import _ from 'lodash';
 import {shortName, isNameTooLong} from './pathUtils';
 
 export function md5Hash(str: string): string {
@@ -29,9 +29,9 @@ export function docuHash(str: string): string {
     return 'index';
   }
   const shortHash = simpleHash(str, 3);
-  const parsedPath = `${kebabCase(str)}-${shortHash}`;
+  const parsedPath = `${_.kebabCase(str)}-${shortHash}`;
   if (isNameTooLong(parsedPath)) {
-    return `${shortName(kebabCase(str))}-${shortHash}`;
+    return `${shortName(_.kebabCase(str))}-${shortHash}`;
   }
   return parsedPath;
 }

package/src/index.ts

@@ -8,7 +8,7 @@
 import logger from '@docusaurus/logger';
 import path from 'path';
 import {createHash} from 'crypto';
-import {mapValues} from 'lodash';
+import _ from 'lodash';
 import fs from 'fs-extra';
 import {URL} from 'url';
 import type {
@@ -22,17 +22,69 @@ import resolvePathnameUnsafe from 'resolve-pathname';
 import {simpleHash, docuHash} from './hashUtils';
 import {DEFAULT_PLUGIN_ID} from './constants';
 
-export * from './constants';
-export * from './urlUtils';
-export * from './tags';
-export * from './markdownParser';
-export * from './markdownLinks';
-export * from './slugger';
-export * from './pathUtils';
-export * from './hashUtils';
-export * from './globUtils';
-export * from './webpackUtils';
-export * from './dataFileUtils';
+export {
+  NODE_MAJOR_VERSION,
+  NODE_MINOR_VERSION,
+  DEFAULT_BUILD_DIR_NAME,
+  DEFAULT_CONFIG_FILE_NAME,
+  BABEL_CONFIG_FILE_NAME,
+  GENERATED_FILES_DIR_NAME,
+  SRC_DIR_NAME,
+  STATIC_DIR_NAME,
+  OUTPUT_STATIC_ASSETS_DIR_NAME,
+  THEME_PATH,
+  DEFAULT_PORT,
+  DEFAULT_PLUGIN_ID,
+  WEBPACK_URL_LOADER_LIMIT,
+} from './constants';
+export {getFileCommitDate, GitNotFoundError} from './gitUtils';
+export {normalizeUrl, getEditUrl} from './urlUtils';
+export {
+  type Tag,
+  type FrontMatterTag,
+  type TaggedItemGroup,
+  normalizeFrontMatterTag,
+  normalizeFrontMatterTags,
+  groupTaggedItems,
+} from './tags';
+export {
+  parseMarkdownHeadingId,
+  createExcerpt,
+  parseFrontMatter,
+  parseMarkdownContentTitle,
+  parseMarkdownString,
+} from './markdownParser';
+export {
+  type ContentPaths,
+  type BrokenMarkdownLink,
+  type ReplaceMarkdownLinksParams,
+  type ReplaceMarkdownLinksReturn,
+  replaceMarkdownLinks,
+} from './markdownLinks';
+export {type SluggerOptions, type Slugger, createSlugger} from './slugger';
+export {
+  isNameTooLong,
+  shortName,
+  posixPath,
+  toMessageRelativeFilePath,
+  aliasedSitePath,
+  escapePath,
+} from './pathUtils';
+export {md5Hash, simpleHash, docuHash} from './hashUtils';
+export {
+  Globby,
+  GlobExcludeDefault,
+  createMatcher,
+  createAbsoluteFilePathMatcher,
+} from './globUtils';
+export {getFileLoaderUtils} from './webpackUtils';
+export {
+  getDataFilePath,
+  getDataFileData,
+  getContentPathList,
+  findFolderContainingFile,
+  getFolderContainingFile,
+} from './dataFileUtils';
 
 const fileHash = new Map<string, string>();
 export async function generate(
@@ -54,7 +106,7 @@ export async function generate(
   // If file already exists but its not in runtime cache yet,
   // we try to calculate the content hash and then compare
   // This is to avoid unnecessary overwriting and we can reuse old file.
-  if (!lastHash && fs.existsSync(filepath)) {
+  if (!lastHash && (await fs.pathExists(filepath))) {
     const lastContent = await fs.readFile(filepath, 'utf8');
     lastHash = createHash('md5').update(lastContent).digest('hex');
     fileHash.set(filepath, lastHash);
@@ -69,8 +121,8 @@ export async function generate(
   }
 }
 
-const indexRE = /(^|.*\/)index\.(md|mdx|js|jsx|ts|tsx)$/i;
-const extRE = /\.(md|mdx|js|jsx|ts|tsx)$/;
+const indexRE = /(?<dirname>^|.*\/)index\.(?:mdx?|jsx?|tsx?)$/i;
+const extRE = /\.(?:mdx?|jsx?|tsx?)$/;
 
 /**
  * Convert filepath to url path.
@@ -126,7 +178,7 @@ export function isValidPathname(str: string): boolean {
     // weird, but is there a better way?
     const parsedPathname = new URL(str, 'https://domain.com').pathname;
     return parsedPathname === str || parsedPathname === encodeURI(str);
-  } catch (e) {
+  } catch {
     return false;
   }
 }
@@ -200,7 +252,8 @@ export function getPluginI18nPath({
   return path.join(
     siteDir,
     'i18n',
-    // namespace first by locale: convenient to work in a single folder for a translator
+    // namespace first by locale: convenient to work in a single folder for a
+    // translator
     locale,
     // Make it convenient to use for single-instance
     // ie: return "docs", not "docs-default" nor "docs/default"
@@ -212,7 +265,8 @@ export function getPluginI18nPath({
 /**
  * @param permalink The URL that the HTML file corresponds to, without base URL
  * @param outDir Full path to the output directory
- * @param trailingSlash The site config option. If provided, only one path will be read.
+ * @param trailingSlash The site config option. If provided, only one path will
+ * be read.
  * @returns This returns a buffer, which you have to decode string yourself if
  * needed. (Not always necessary since the output isn't for human consumption
  * anyways, and most HTML manipulation libs accept buffers)
@@ -223,23 +277,25 @@ export async function readOutputHTMLFile(
   trailingSlash: boolean | undefined,
 ): Promise<Buffer> {
   const withTrailingSlashPath = path.join(outDir, permalink, 'index.html');
-  const withoutTrailingSlashPath = path.join(outDir, `${permalink}.html`);
+  const withoutTrailingSlashPath = path.join(
+    outDir,
+    `${permalink.replace(/\/$/, '')}.html`,
+  );
   if (trailingSlash) {
     return fs.readFile(withTrailingSlashPath);
   } else if (trailingSlash === false) {
     return fs.readFile(withoutTrailingSlashPath);
-  } else {
-    const HTMLPath = await findAsyncSequential(
-      [withTrailingSlashPath, withoutTrailingSlashPath],
-      fs.pathExists,
+  }
+  const HTMLPath = await findAsyncSequential(
+    [withTrailingSlashPath, withoutTrailingSlashPath],
+    fs.pathExists,
+  );
+  if (!HTMLPath) {
+    throw new Error(
+      `Expected output HTML file to be found at ${withTrailingSlashPath}`,
     );
-    if (!HTMLPath) {
-      throw new Error(
-        `Expected output HTML file to be found at ${withTrailingSlashPath}`,
-      );
-    }
-    return fs.readFile(HTMLPath);
   }
+  return fs.readFile(HTMLPath);
 }
 
 export async function mapAsyncSequential<T, R>(
@@ -247,7 +303,6 @@ export async function mapAsyncSequential<T, R>(
   action: (t: T) => Promise<R>,
 ): Promise<R[]> {
   const results: R[] = [];
-  // eslint-disable-next-line no-restricted-syntax
   for (const t of array) {
     const result = await action(t);
     results.push(result);
@@ -259,7 +314,6 @@ export async function findAsyncSequential<T>(
   array: T[],
   predicate: (t: T) => Promise<boolean>,
 ): Promise<T | undefined> {
-  // eslint-disable-next-line no-restricted-syntax
   for (const t of array) {
     if (await predicate(t)) {
       return t;
@@ -307,7 +361,7 @@ export function updateTranslationFileMessages(
 ): TranslationFile {
   return {
     ...translationFile,
-    content: mapValues(translationFile.content, (translation) => ({
+    content: _.mapValues(translationFile.content, (translation) => ({
       ...translation,
       message: updateMessage(translation.message),
     })),

package/src/markdownLinks.ts

@@ -51,7 +51,8 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
       if (!fencedBlock) {
         fencedBlock = true;
         [lastCodeFence] = line.trim().match(/^`+/)!;
-        // If we are in a ````-fenced block, all ``` would be plain text instead of fences
+        // If we are in a ````-fenced block, all ``` would be plain text instead
+        // of fences
       } else if (line.trim().match(/^`+/)![0].length >= lastCodeFence.length) {
         fencedBlock = false;
       }
@@ -62,13 +63,15 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
 
     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
+    // This is [Document 1](doc1.md) -> we replace this doc1.md with correct
+    // ink
     // [doc1]: doc1.md -> we replace this doc1.md with correct link
-    const mdRegex = /(?:(?:\]\()|(?:\]:\s?))(?!https?)([^'")\]\s>]+\.mdx?)/g;
+    const mdRegex =
+      /(?:(?:\]\()|(?:\]:\s*))(?!https?:\/\/|@site\/)(?<filename>[^'")\]\s>]+\.mdx?)/g;
     let mdMatch = mdRegex.exec(modifiedLine);
     while (mdMatch !== null) {
       // Replace it to correct html link.
-      const mdLink = mdMatch[1];
+      const mdLink = mdMatch.groups!.filename;
 
       const sourcesToTry = [
         path.resolve(path.dirname(filePath), decodeURIComponent(mdLink)),
@@ -85,7 +88,8 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
         : undefined;
 
       if (permalink) {
-        // MDX won't be happy if the permalink contains a space, we need to convert it to %20
+        // MDX won't be happy if the permalink contains a space, we need to
+        // convert it to %20
         const encodedPermalink = permalink
           .split('/')
           .map((part) => part.replace(/\s/g, '%20'))

package/src/markdownParser.ts

@@ -14,16 +14,15 @@ export function parseMarkdownHeadingId(heading: string): {
   text: string;
   id?: string;
 } {
-  const customHeadingIdRegex = /^(.*?)\s*\{#([\w-]+)\}$/;
+  const customHeadingIdRegex = /^(?<text>.*?)\s*\{#(?<id>[\w-]+)\}$/;
   const matches = customHeadingIdRegex.exec(heading);
   if (matches) {
     return {
-      text: matches[1],
-      id: matches[2],
+      text: matches.groups!.text,
+      id: matches.groups!.id,
     };
-  } else {
-    return {text: heading, id: undefined};
   }
+  return {text: heading, id: undefined};
 }
 
 // Hacky way of stripping out import statements from the excerpt
@@ -39,7 +38,6 @@ export function createExcerpt(fileString: string): string | undefined {
   let lastCodeFence = '';
 
   /* eslint-disable no-continue */
-  // eslint-disable-next-line no-restricted-syntax
   for (const fileLine of fileLines) {
     // Skip empty line.
     if (!fileLine.trim()) {
@@ -47,7 +45,7 @@ export function createExcerpt(fileString: string): string | undefined {
     }
 
     // Skip import/export declaration.
-    if (/^\s*?import\s.*(from.*)?;?|export\s.*{.*};?/.test(fileLine)) {
+    if (/^(?:import|export)\s.*/.test(fileLine)) {
       continue;
     }
 
@@ -56,7 +54,8 @@ export function createExcerpt(fileString: string): string | undefined {
       if (!inCode) {
         inCode = true;
         [lastCodeFence] = fileLine.trim().match(/^`+/)!;
-        // If we are in a ````-fenced block, all ``` would be plain text instead of fences
+        // If we are in a ````-fenced block, all ``` would be plain text instead
+        // of fences
       } else if (
         fileLine.trim().match(/^`+/)![0].length >= lastCodeFence.length
       ) {
@@ -71,25 +70,27 @@ export function createExcerpt(fileString: string): string | undefined {
       // Remove HTML tags.
       .replace(/<[^>]*>/g, '')
       // Remove Title headers
-      .replace(/^#\s*([^#]*)\s*#?/gm, '')
+      .replace(/^#\s*[^#]*\s*#?/gm, '')
       // Remove Markdown + ATX-style headers
-      .replace(/^#{1,6}\s*([^#]*)\s*(#{1,6})?/gm, '$1')
-      // Remove emphasis and strikethroughs.
-      .replace(/([*_~]{1,3})(\S.*?\S{0,1})\1/g, '$2')
+      .replace(/^#{1,6}\s*(?<text>[^#]*)\s*(?:#{1,6})?/gm, '$1')
+      // Remove emphasis.
+      .replace(/(?<opening>[*_]{1,3})(?<text>.*?)\1/g, '$2')
+      // Remove strikethroughs.
+      .replace(/~~(?<text>\S.*\S)~~/g, '$1')
       // Remove images.
-      .replace(/!\[(.*?)\][[(].*?[\])]/g, '$1')
+      .replace(/!\[(?<alt>.*?)\][[(].*?[\])]/g, '$1')
       // Remove footnotes.
-      .replace(/\[\^.+?\](: .*?$)?/g, '')
+      .replace(/\[\^.+?\](?:: .*?$)?/g, '')
       // Remove inline links.
-      .replace(/\[(.*?)\][[(].*?[\])]/g, '$1')
+      .replace(/\[(?<alt>.*?)\][[(].*?[\])]/g, '$1')
       // Remove inline code.
-      .replace(/`(.+?)`/g, '$1')
+      .replace(/`(?<text>.+?)`/g, '$1')
       // Remove blockquotes.
       .replace(/^\s{0,3}>\s?/g, '')
       // Remove admonition definition.
-      .replace(/(:{3}.*)/, '')
+      .replace(/:::.*/, '')
       // Remove Emoji names within colons include preceding whitespace.
-      .replace(/\s?(:(::|[^:\n])+:)/g, '')
+      .replace(/\s?:(?:::|[^:\n])+:/g, '')
       // Remove custom Markdown heading id.
       .replace(/{#*[\w-]+}/, '')
       .trim();
@@ -113,9 +114,11 @@ export function parseFrontMatter(markdownFileContent: string): {
   };
 }
 
-// Try to convert markdown heading as text
-// Does not need to be perfect, it is only used as a fallback when frontMatter.title is not provided
-// For now, we just unwrap possible inline code blocks (# `config.js`)
+/**
+ * Try to convert markdown heading to text. Does not need to be perfect, it is
+ * only used as a fallback when frontMatter.title is not provided. For now, we
+ * just unwrap possible inline code blocks (# `config.js`)
+ */
 function toTextContentTitle(contentTitle: string): string {
   if (contentTitle.startsWith('`') && contentTitle.endsWith('`')) {
     return contentTitle.substring(1, contentTitle.length - 1);
@@ -132,9 +135,9 @@ export function parseMarkdownContentTitle(
   const content = contentUntrimmed.trim();
 
   const IMPORT_STATEMENT =
-    /import\s+(([\w*{}\s\n,]+)from\s+)?["'\s]([@\w/_.-]+)["'\s];?|\n/.source;
+    /import\s+(?:[\w*{}\s\n,]+from\s+)?["'\s][@\w/_.-]+["'\s];?|\n/.source;
   const REGULAR_TITLE =
-    /(?<pattern>#\s*(?<title>[^#\n{]*)+[ \t]*(?<suffix>({#*[\w-]+})|#)?\n*?)/
+    /(?<pattern>#\s*(?<title>[^#\n{]*)+[ \t]*(?<suffix>(?:{#*[\w-]+})|#)?\n*?)/
       .source;
   const ALTERNATE_TITLE = /(?<pattern>\s*(?<title>[^\n]*)\s*\n[=]+)/.source;
 
@@ -152,15 +155,14 @@ export function parseMarkdownContentTitle(
 
   if (!pattern || !title) {
     return {content, contentTitle: undefined};
-  } else {
-    const newContent = removeContentTitleOption
-      ? content.replace(pattern, '')
-      : content;
-    return {
-      content: newContent.trim(),
-      contentTitle: toTextContentTitle(title.trim()).trim(),
-    };
   }
+  const newContent = removeContentTitleOption
+    ? content.replace(pattern, '')
+    : content;
+  return {
+    content: newContent.trim(),
+    contentTitle: toTextContentTitle(title.trim()).trim(),
+  };
 }
 
 type ParsedMarkdown = {
@@ -191,9 +193,9 @@ export function parseMarkdownString(
       contentTitle,
       excerpt,
     };
-  } catch (e) {
+  } catch (err) {
     logger.error(`Error while parsing Markdown front matter.
 This can happen if you use special characters in front matter values (try using double quotes around that value).`);
-    throw e;
+    throw err;
   }
 }

package/src/pathUtils.ts

@@ -9,7 +9,8 @@
 
 import path from 'path';
 
-// MacOS (APFS) and Windows (NTFS) filename length limit = 255 chars, Others = 255 bytes
+// MacOS (APFS) and Windows (NTFS) filename length limit = 255 chars,
+// Others = 255 bytes
 const MAX_PATH_SEGMENT_CHARS = 255;
 const MAX_PATH_SEGMENT_BYTES = 255;
 // Space for appending things to the string like file extensions and so on
@@ -19,7 +20,7 @@ const isMacOs = () => process.platform === 'darwin';
 const isWindows = () => process.platform === 'win32';
 
 export const isNameTooLong = (str: string): boolean =>
-  // This is actually not entirely correct: we can't assume FS from OS. But good enough?
+  // Not entirely correct: we can't assume FS from OS. But good enough?
   isMacOs() || isWindows()
     ? str.length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_CHARS // MacOS (APFS) and Windows (NTFS) filename length limit (255 chars)
     : Buffer.from(str).length + SPACE_FOR_APPENDING > MAX_PATH_SEGMENT_BYTES; // Other (255 bytes)
@@ -56,7 +57,8 @@ export const shortName = (str: string): string => {
 export function posixPath(str: string): string {
   const isExtendedLengthPath = /^\\\\\?\\/.test(str);
 
-  // Forward slashes are only valid Windows paths when they don't contain non-ascii characters.
+  // Forward slashes are only valid Windows paths when they don't contain non-
+  // ascii characters.
   // eslint-disable-next-line no-control-regex
   const hasNonAscii = /[^\u0000-\u0080]+/.test(str);
 
@@ -66,13 +68,18 @@ export function posixPath(str: string): string {
   return str.replace(/\\/g, '/');
 }
 
-// When you want to display a path in a message/warning/error,
-// it's more convenient to:
-// - make it relative to cwd()
-// - convert to posix (ie not using windows \ path separator)
-// This way, Jest tests can run more reliably on any computer/CI
-// on both Unix/Windows
-// For Windows users this is not perfect (as they see / instead of \) but it's probably good enough
+/**
+ * When you want to display a path in a message/warning/error, it's more
+ * convenient to:
+ *
+ * - make it relative to `cwd()`
+ * - convert to posix (ie not using windows \ path separator)
+ *
+ * This way, Jest tests can run more reliably on any computer/CI on both
+ * Unix/Windows
+ * For Windows users this is not perfect (as they see / instead of \) but it's
+ * probably good enough
+ */
 export function toMessageRelativeFilePath(filePath: string): string {
   return posixPath(path.relative(process.cwd(), filePath));
 }
@@ -92,7 +99,8 @@ export function aliasedSitePath(filePath: string, siteDir: string): string {
 /**
  * When you have a path like C:\X\Y
  * It is not safe to use directly when generating code
- * For example, this would fail due to unescaped \: `<img src={require('${filePath}')} />`
+ * For example, this would fail due to unescaped \:
+ * `<img src={require('${filePath}')} />`
  * But this would work: `<img src={require('${escapePath(filePath)}')} />`
  *
  * posixPath can't be used in all cases, because forward slashes are only valid