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

package/src/constants.ts

@@ -5,34 +5,90 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/** Node major version, directly read from env. */
 export const NODE_MAJOR_VERSION = parseInt(
-  process.versions.node.split('.')[0],
+  process.versions.node.split('.')[0]!,
   10,
 );
+/** Node minor version, directly read from env. */
 export const NODE_MINOR_VERSION = parseInt(
-  process.versions.node.split('.')[1],
+  process.versions.node.split('.')[1]!,
   10,
 );
 
-// Can be overridden with cli option --out-dir
+/** Docusaurus core version. */
+// eslint-disable-next-line global-require, @typescript-eslint/no-var-requires
+export const DOCUSAURUS_VERSION = require('../package.json').version;
+
+/**
+ * Can be overridden with cli option `--out-dir`. Code should generally use
+ * `context.outDir` instead (which is always absolute and localized).
+ */
 export const DEFAULT_BUILD_DIR_NAME = 'build';
 
-// Can be overridden with cli option --config
+/**
+ * Can be overridden with cli option `--config`. Code should generally use
+ * `context.siteConfigPath` instead (which is always absolute).
+ */
 export const DEFAULT_CONFIG_FILE_NAME = 'docusaurus.config.js';
 
+/** Can be absolute or relative to site directory. */
 export const BABEL_CONFIG_FILE_NAME =
-  process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME || 'babel.config.js';
+  process.env.DOCUSAURUS_BABEL_CONFIG_FILE_NAME ?? 'babel.config.js';
 
+/**
+ * Can be absolute or relative to site directory. Code should generally use
+ * `context.generatedFilesDir` instead (which is always absolute).
+ */
 export const GENERATED_FILES_DIR_NAME =
-  process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME || '.docusaurus';
+  process.env.DOCUSAURUS_GENERATED_FILES_DIR_NAME ?? '.docusaurus';
 
+/**
+ * We would assume all of the site's JS code lives in here and not outside.
+ * Relative to the site directory.
+ */
 export const SRC_DIR_NAME = 'src';
-export const STATIC_DIR_NAME = 'static';
-export const OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets'; // files handled by webpack, hashed (can be cached aggressively)
+
+/**
+ * Can be overridden with `config.staticDirectories`. Code should use
+ * `context.siteConfig.staticDirectories` instead (which is always absolute).
+ */
+export const DEFAULT_STATIC_DIR_NAME = 'static';
+
+/**
+ * Files here are handled by webpack, hashed (can be cached aggressively).
+ * Relative to the build output folder.
+ */
+export const OUTPUT_STATIC_ASSETS_DIR_NAME = 'assets';
+
+/**
+ * Components in this directory will receive the `@theme` alias and be able to
+ * shadow default theme components.
+ */
 export const THEME_PATH = `${SRC_DIR_NAME}/theme`;
+
+/**
+ * All translation-related data live here, relative to site directory. Content
+ * will be namespaced by locale.
+ */
+export const I18N_DIR_NAME = 'i18n';
+
+/**
+ * Translations for React code.
+ */
+export const CODE_TRANSLATIONS_FILE_NAME = 'code.json';
+
+/** Dev server opens on this port by default. */
 export const DEFAULT_PORT = 3000;
+
+/** Default plugin ID. */
 export const DEFAULT_PLUGIN_ID = 'default';
 
-// Temporary fix for https://github.com/facebook/docusaurus/issues/5493
+/**
+ * Allow overriding the limit after which the url loader will no longer inline
+ * assets.
+ *
+ * @see https://github.com/facebook/docusaurus/issues/5493
+ */
 export const WEBPACK_URL_LOADER_LIMIT =
   process.env.WEBPACK_URL_LOADER_LIMIT ?? 10000;

package/src/dataFileUtils.ts

@@ -13,31 +13,47 @@ import type {ContentPaths} from './markdownLinks';
 import logger from '@docusaurus/logger';
 
 type DataFileParams = {
+  /** Path to the potential data file, relative to `contentPaths` */
   filePath: string;
+  /**
+   * Includes the base path and localized path, both of which are eligible for
+   * sourcing data files. Both paths should be absolute.
+   */
   contentPaths: ContentPaths;
 };
 
+/**
+ * Looks for a data file in the potential content paths; loads a localized data
+ * file in priority.
+ *
+ * @returns An absolute path to the data file, or `undefined` if there isn't one.
+ */
 export async function getDataFilePath({
   filePath,
   contentPaths,
 }: DataFileParams): Promise<string | undefined> {
-  // Loads a localized data file in priority
   const contentPath = await findFolderContainingFile(
     getContentPathList(contentPaths),
     filePath,
   );
   if (contentPath) {
-    return path.join(contentPath, filePath);
+    return path.resolve(contentPath, filePath);
   }
   return undefined;
 }
 
 /**
- * Looks up for a data file in the content paths, returns the normalized object.
- * Throws when validation fails; returns undefined when file not found
+ * Looks up for a data file in the content paths, returns the object validated
+ * and normalized according to the `validate` callback.
+ *
+ * @returns `undefined` when file not found
+ * @throws Throws when validation fails, displaying a helpful context message.
  */
 export async function getDataFileData<T>(
-  params: DataFileParams & {fileType: string},
+  params: DataFileParams & {
+    /** Used for the "The X file looks invalid" message. */
+    fileType: string;
+  },
   validate: (content: unknown) => T,
 ): Promise<T | undefined> {
   const filePath = await getDataFilePath(params);
@@ -49,18 +65,26 @@ export async function getDataFileData<T>(
     const unsafeContent = Yaml.load(contentString);
     return validate(unsafeContent);
   } 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 err;
   }
 }
 
-// Order matters: we look in priority in localized folder
+/**
+ * Takes the `contentPaths` data structure and returns an ordered path list
+ * indicating their priorities. For all data, we look in the localized folder
+ * in priority.
+ */
 export function getContentPathList(contentPaths: ContentPaths): string[] {
   return [contentPaths.contentPathLocalized, contentPaths.contentPath];
 }
 
-// return the first folder path in which the file exists in
+/**
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists, or `undefined` if
+ * none is found.
+ */
 export async function findFolderContainingFile(
   folderPaths: string[],
   relativeFilePath: string,
@@ -70,6 +94,16 @@ export async function findFolderContainingFile(
   );
 }
 
+/**
+ * Fail-fast alternative to `findFolderContainingFile`.
+ *
+ * @param folderPaths a list of absolute paths.
+ * @param relativeFilePath file path relative to each `folderPaths`.
+ * @returns the first folder path in which the file exists.
+ * @throws Throws if no file can be found. You should use this method only when
+ * you actually know the file exists (e.g. when the `relativeFilePath` is read
+ * with a glob and you are just trying to localize it)
+ */
 export async function getFolderContainingFile(
   folderPaths: string[],
   relativeFilePath: string,
@@ -78,12 +112,10 @@ export async function getFolderContainingFile(
     folderPaths,
     relativeFilePath,
   );
-  // should never happen, as the source was read from the FS anyway...
   if (!maybeFolderPath) {
     throw new Error(
-      `File "${relativeFilePath}" does not exist in any of these folders:\n- ${folderPaths.join(
-        '\n- ',
-      )}]`,
+      `File "${relativeFilePath}" does not exist in any of these folders:
+- ${folderPaths.join('\n- ')}`,
     );
   }
   return maybeFolderPath;

package/src/emitUtils.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 fs from 'fs-extra';
+import {createHash} from 'crypto';
+import {findAsyncSequential} from './jsUtils';
+
+const fileHash = new Map<string, string>();
+
+/**
+ * Outputs a file to the generated files directory. Only writes files if content
+ * differs from cache (for hot reload performance).
+ *
+ * @param generatedFilesDir Absolute path.
+ * @param file Path relative to `generatedFilesDir`. File will always be
+ * outputted; no need to ensure directory exists.
+ * @param content String content to write.
+ * @param skipCache If `true` (defaults as `true` for production), file is
+ * force-rewritten, skipping cache.
+ */
+export async function generate(
+  generatedFilesDir: string,
+  file: string,
+  content: string,
+  skipCache: boolean = process.env.NODE_ENV === 'production',
+): Promise<void> {
+  const filepath = path.resolve(generatedFilesDir, file);
+
+  if (skipCache) {
+    await fs.outputFile(filepath, content);
+    // Cache still needs to be reset, otherwise, writing "A", "B", and "A" where
+    // "B" skips cache will cause the last "A" not be able to overwrite as the
+    // first "A" remains in cache. But if the file never existed in cache, no
+    // need to register it.
+    if (fileHash.get(filepath)) {
+      fileHash.set(filepath, createHash('md5').update(content).digest('hex'));
+    }
+    return;
+  }
+
+  let lastHash = fileHash.get(filepath);
+
+  // If file already exists but it's 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 && (await fs.pathExists(filepath))) {
+    const lastContent = await fs.readFile(filepath, 'utf8');
+    lastHash = createHash('md5').update(lastContent).digest('hex');
+    fileHash.set(filepath, lastHash);
+  }
+
+  const currentHash = createHash('md5').update(content).digest('hex');
+
+  if (lastHash !== currentHash) {
+    await fs.outputFile(filepath, content);
+    fileHash.set(filepath, currentHash);
+  }
+}
+
+/**
+ * @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.
+ * @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)
+ * @throws Throws when the HTML file is not found at any of the potential paths.
+ * This should never happen as it would lead to a 404.
+ */
+export async function readOutputHTMLFile(
+  permalink: string,
+  outDir: string,
+  trailingSlash: boolean | undefined,
+): Promise<Buffer> {
+  const withTrailingSlashPath = path.join(outDir, permalink, 'index.html');
+  const withoutTrailingSlashPath = path.join(
+    outDir,
+    `${permalink.replace(/\/$/, '')}.html`,
+  );
+  const HTMLPath = await findAsyncSequential(
+    [
+      trailingSlash !== false && withTrailingSlashPath,
+      trailingSlash !== true && withoutTrailingSlashPath,
+    ].filter((p): p is string => Boolean(p)),
+    fs.pathExists,
+  );
+  if (!HTMLPath) {
+    throw new Error(
+      `Expected output HTML file to be found at ${withTrailingSlashPath}.`,
+    );
+  }
+  return fs.readFile(HTMLPath);
+}

package/src/gitUtils.ts

@@ -8,9 +8,70 @@
 import path from 'path';
 import shell from 'shelljs';
 
+/** Custom error thrown when git is not found in `PATH`. */
 export class GitNotFoundError extends Error {}
 
-export const getFileCommitDate = (
+/** Custom error thrown when the current file is not tracked by git. */
+export class FileNotTrackedError extends Error {}
+
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {@link GitNotFoundError} If git is not found in `PATH`.
+ * @throws {@link FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
+export function getFileCommitDate(
+  /** Absolute path to the file. */
+  file: string,
+  args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    /** Use `includeAuthor: true` to get the author information as well. */
+    includeAuthor?: false;
+  },
+): {
+  /** Relevant commit date. */
+  date: Date;
+  /** Timestamp in **seconds**, as returned from git. */
+  timestamp: number;
+};
+/**
+ * Fetches the git history of a file and returns a relevant commit date.
+ * It gets the commit date instead of author date so that amended commits
+ * can have their dates updated.
+ *
+ * @throws {@link GitNotFoundError} If git is not found in `PATH`.
+ * @throws {@link FileNotTrackedError} If the current file is not tracked by git.
+ * @throws Also throws when `git log` exited with non-zero, or when it outputs
+ * unexpected text.
+ */
+export function getFileCommitDate(
+  /** Absolute path to the file. */
+  file: string,
+  args: {
+    /**
+     * `"oldest"` is the commit that added the file, following renames;
+     * `"newest"` is the last commit that edited the file.
+     */
+    age?: 'oldest' | 'newest';
+    includeAuthor: true;
+  },
+): {
+  /** Relevant commit date. */
+  date: Date;
+  /** Timestamp in **seconds**, as returned from git. */
+  timestamp: number;
+  /** The author's name, as returned from git. */
+  author: string;
+};
+export function getFileCommitDate(
   file: string,
   {
     age = 'oldest',
@@ -23,7 +84,7 @@ export const getFileCommitDate = (
   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.`,
@@ -36,9 +97,6 @@ export const getFileCommitDate = (
     );
   }
 
-  const fileBasename = path.basename(file);
-  const fileDirname = path.dirname(file);
-
   let formatArg = '--format=%ct';
   if (includeAuthor) {
     formatArg += ',%an';
@@ -52,10 +110,10 @@ export const getFileCommitDate = (
   }
 
   const result = shell.exec(
-    `git log ${extraArgs} ${formatArg} -- "${fileBasename}"`,
+    `git log ${extraArgs} ${formatArg} -- "${path.basename(file)}"`,
     {
-      // cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
-      cwd: fileDirname,
+      // Setting cwd is important, see: https://github.com/facebook/docusaurus/pull/5048
+      cwd: path.dirname(file),
       silent: true,
     },
   );
@@ -70,24 +128,26 @@ export const getFileCommitDate = (
   }
 
   const output = result.stdout.trim();
+
+  if (!output) {
+    throw new FileNotTrackedError(
+      `Failed to retrieve the git history for file "${file}" because the file is not tracked by git.`,
+    );
+  }
+
   const match = output.match(regex);
 
-  if (
-    !match ||
-    !match.groups ||
-    !match.groups.timestamp ||
-    (includeAuthor && !match.groups.author)
-  ) {
+  if (!match) {
     throw new Error(
       `Failed to retrieve the git history for file "${file}" with unexpected output: ${output}`,
     );
   }
 
-  const timestamp = Number(match.groups.timestamp);
+  const timestamp = Number(match.groups!.timestamp);
   const date = new Date(timestamp * 1000);
 
   if (includeAuthor) {
-    return {date, timestamp, author: match.groups.author};
+    return {date, timestamp, author: match.groups!.author!};
   }
   return {date, timestamp};
-};
+}

package/src/globUtils.ts

@@ -10,35 +10,56 @@
 import Micromatch from 'micromatch'; // Note: Micromatch is used by Globby
 import path from 'path';
 
+/** A re-export of the globby instance. */
 export {default as Globby} from 'globby';
 
-// The default patterns we ignore when globbing
-// using _ prefix for exclusion by convention
+/**
+ * The default glob patterns we ignore when sourcing content.
+ * - Ignore files and folders starting with `_` recursively
+ * - Ignore tests
+ */
 export const GlobExcludeDefault = [
-  // Ignore files starting with _
   '**/_*.{js,jsx,ts,tsx,md,mdx}',
-
-  // Ignore folders starting with _ (including folder content)
   '**/_*/**',
-
-  // Ignore tests
   '**/*.test.{js,jsx,ts,tsx}',
   '**/__tests__/**',
 ];
 
 type Matcher = (str: string) => boolean;
 
+/**
+ * A very thin wrapper around `Micromatch.makeRe`.
+ *
+ * @see {@link createAbsoluteFilePathMatcher}
+ * @param patterns A list of glob patterns. If the list is empty, it defaults to
+ * matching none.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
 export function createMatcher(patterns: string[]): Matcher {
+  if (patterns.length === 0) {
+    // `/(?:)/.test("foo")` is `true`
+    return () => false;
+  }
   const regexp = new RegExp(
     patterns.map((pattern) => Micromatch.makeRe(pattern).source).join('|'),
   );
   return (str) => regexp.test(str);
 }
 
-// We use match patterns like '**/_*/**',
-// This function permits to help to:
-// Match /user/sebastien/website/docs/_partials/xyz.md
-// Ignore /user/_sebastien/website/docs/partials/xyz.md
+/**
+ * We use match patterns like `"** /_* /**"` (ignore the spaces), where `"_*"`
+ * should only be matched within a subfolder. This function would:
+ * - Match `/user/sebastien/website/docs/_partials/xyz.md`
+ * - Ignore `/user/_sebastien/website/docs/partials/xyz.md`
+ *
+ * @param patterns A list of glob patterns.
+ * @param rootFolders A list of root folders to resolve the glob from.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns, resolved from the first root folder that contains the path.
+ * @throws Throws when the returned matcher receives a path that doesn't belong
+ * to any of the `rootFolders`.
+ */
 export function createAbsoluteFilePathMatcher(
   patterns: string[],
   rootFolders: string[],
@@ -51,8 +72,8 @@ export function createAbsoluteFilePathMatcher(
     );
     if (!rootFolder) {
       throw new Error(
-        `createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders ${JSON.stringify(
-          rootFolders,
+        `createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders: ${rootFolders.join(
+          ', ',
         )}`,
       );
     }

package/src/hashUtils.ts

@@ -9,20 +9,21 @@ import {createHash} from 'crypto';
 import _ from 'lodash';
 import {shortName, isNameTooLong} from './pathUtils';
 
+/** Thin wrapper around `crypto.createHash("md5")`. */
 export function md5Hash(str: string): string {
   return createHash('md5').update(str).digest('hex');
 }
 
+/** Creates an MD5 hash and truncates it to the given length. */
 export function simpleHash(str: string, length: number): string {
-  return md5Hash(str).substr(0, length);
+  return md5Hash(str).substring(0, length);
 }
 
 // Based on https://github.com/gatsbyjs/gatsby/pull/21518/files
 /**
- * Given an input string, convert to kebab-case and append a hash.
- * Avoid str collision.
- * Also removes part of the string if its larger than the allowed
- * filename per OS. Avoids ERRNAMETOOLONG error.
+ * Given an input string, convert to kebab-case and append a hash, avoiding name
+ * collision. Also removes part of the string if its larger than the allowed
+ * filename per OS, avoiding `ERRNAMETOOLONG` error.
  */
 export function docuHash(str: string): string {
   if (str === '/') {

package/src/i18nUtils.ts

@@ -0,0 +1,115 @@
+/**
+ * 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 _ from 'lodash';
+import type {
+  TranslationFileContent,
+  TranslationFile,
+  I18n,
+} from '@docusaurus/types';
+import {DEFAULT_PLUGIN_ID, I18N_DIR_NAME} from './constants';
+import {normalizeUrl} from './urlUtils';
+
+/**
+ * Takes a list of translation file contents, and shallow-merges them into one.
+ */
+export function mergeTranslations(
+  contents: TranslationFileContent[],
+): TranslationFileContent {
+  return contents.reduce((acc, content) => ({...acc, ...content}), {});
+}
+
+/**
+ * Useful to update all the messages of a translation file. Used in tests to
+ * simulate translations.
+ */
+export function updateTranslationFileMessages(
+  translationFile: TranslationFile,
+  updateMessage: (message: string) => string,
+): TranslationFile {
+  return {
+    ...translationFile,
+    content: _.mapValues(translationFile.content, (translation) => ({
+      ...translation,
+      message: updateMessage(translation.message),
+    })),
+  };
+}
+
+/**
+ * Takes everything needed and constructs a plugin i18n path. Plugins should
+ * expect everything it needs for translations to be found under this path.
+ */
+export function getPluginI18nPath({
+  siteDir,
+  locale,
+  pluginName,
+  pluginId = DEFAULT_PLUGIN_ID,
+  subPaths = [],
+}: {
+  siteDir: string;
+  locale: string;
+  pluginName: string;
+  pluginId?: string | undefined;
+  subPaths?: string[];
+}): string {
+  return path.join(
+    siteDir,
+    I18N_DIR_NAME,
+    // 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"
+    `${pluginName}${pluginId === DEFAULT_PLUGIN_ID ? '' : `-${pluginId}`}`,
+    ...subPaths,
+  );
+}
+
+/**
+ * Takes a path and returns a localized a version (which is basically `path +
+ * i18n.currentLocale`).
+ */
+export function localizePath({
+  pathType,
+  path: originalPath,
+  i18n,
+  options = {},
+}: {
+  /**
+   * FS paths will treat Windows specially; URL paths will always have a
+   * trailing slash to make it a valid base URL.
+   */
+  pathType: 'fs' | 'url';
+  /** The path, URL or file path, to be localized. */
+  path: string;
+  /** The current i18n context. */
+  i18n: I18n;
+  options?: {
+    /**
+     * By default, we don't localize the path of defaultLocale. This option
+     * would override that behavior. Setting `false` is useful for `yarn build
+     * -l zh-Hans` to always emit into the root build directory.
+     */
+    localizePath?: boolean;
+  };
+}): string {
+  const shouldLocalizePath: boolean =
+    //
+    options.localizePath ?? i18n.currentLocale !== i18n.defaultLocale;
+
+  if (!shouldLocalizePath) {
+    return originalPath;
+  }
+  // FS paths need special care, for Windows support
+  if (pathType === 'fs') {
+    return path.join(originalPath, i18n.currentLocale);
+  }
+  // Url paths; add a trailing slash so it's a valid base URL
+  return normalizeUrl([originalPath, i18n.currentLocale, '/']);
+}