@docusaurus/utils 0.0.0-4756 → 0.0.0-4760

package/src/globUtils.ts

@@ -10,24 +10,31 @@
 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.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
 export function createMatcher(patterns: string[]): Matcher {
   const regexp = new RegExp(
     patterns.map((pattern) => Micromatch.makeRe(pattern).source).join('|'),
@@ -35,10 +42,19 @@ export function createMatcher(patterns: string[]): Matcher {
   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 +67,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

@@ -8,16 +8,21 @@
 import path from 'path';
 import _ from 'lodash';
 import type {TranslationFileContent, TranslationFile} from '@docusaurus/types';
-import {DEFAULT_PLUGIN_ID} from './constants';
+import {DEFAULT_PLUGIN_ID, I18N_DIR_NAME} from './constants';
 
+/**
+ * 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
+/**
+ * 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,
@@ -31,6 +36,10 @@ export function updateTranslationFileMessages(
   };
 }
 
+/**
+ * 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,
@@ -46,7 +55,7 @@ export function getPluginI18nPath({
 }): string {
   return path.join(
     siteDir,
-    'i18n',
+    I18N_DIR_NAME,
     // namespace first by locale: convenient to work in a single folder for a
     // translator
     locale,

package/src/index.ts

@@ -13,9 +13,11 @@ export {
   BABEL_CONFIG_FILE_NAME,
   GENERATED_FILES_DIR_NAME,
   SRC_DIR_NAME,
-  STATIC_DIR_NAME,
+  DEFAULT_STATIC_DIR_NAME,
   OUTPUT_STATIC_ASSETS_DIR_NAME,
   THEME_PATH,
+  I18N_DIR_NAME,
+  CODE_TRANSLATIONS_FILE_NAME,
   DEFAULT_PORT,
   DEFAULT_PLUGIN_ID,
   WEBPACK_URL_LOADER_LIMIT,
@@ -34,7 +36,6 @@ export {
 export {
   removeSuffix,
   removePrefix,
-  getElementsAround,
   mapAsyncSequential,
   findAsyncSequential,
   reportMessage,
@@ -56,8 +57,6 @@ export {
 export {
   type Tag,
   type FrontMatterTag,
-  type TaggedItemGroup,
-  normalizeFrontMatterTag,
   normalizeFrontMatterTags,
   groupTaggedItems,
 } from './tags';
@@ -73,8 +72,6 @@ export {
 export {
   type ContentPaths,
   type BrokenMarkdownLink,
-  type ReplaceMarkdownLinksParams,
-  type ReplaceMarkdownLinksReturn,
   replaceMarkdownLinks,
 } from './markdownLinks';
 export {type SluggerOptions, type Slugger, createSlugger} from './slugger';

package/src/jsUtils.ts

@@ -8,36 +8,27 @@
 import type {ReportingSeverity} from '@docusaurus/types';
 import logger from '@docusaurus/logger';
 
+/** Removes a given string suffix from `str`. */
 export function removeSuffix(str: string, suffix: string): string {
   if (suffix === '') {
-    return str; // always returns "" otherwise!
+    // str.slice(0, 0) is ""
+    return str;
   }
   return str.endsWith(suffix) ? str.slice(0, -suffix.length) : str;
 }
 
+/** Removes a given string prefix from `str`. */
 export function removePrefix(str: string, prefix: string): string {
   return str.startsWith(prefix) ? str.slice(prefix.length) : str;
 }
 
-export function getElementsAround<T>(
-  array: T[],
-  aroundIndex: number,
-): {
-  next: T | undefined;
-  previous: T | undefined;
-} {
-  const min = 0;
-  const max = array.length - 1;
-  if (aroundIndex < min || aroundIndex > max) {
-    throw new Error(
-      `Valid "aroundIndex" for array (of size ${array.length}) are between ${min} and ${max}, but you provided ${aroundIndex}.`,
-    );
-  }
-  const previous = aroundIndex === min ? undefined : array[aroundIndex - 1];
-  const next = aroundIndex === max ? undefined : array[aroundIndex + 1];
-  return {previous, next};
-}
-
+/**
+ * `Array#map` for async operations where order matters.
+ * @param array The array to traverse.
+ * @param action An async action to be performed on every array item. Will be
+ * awaited before working on the next.
+ * @returns The list of results returned from every `action(item)`
+ */
 export async function mapAsyncSequential<T, R>(
   array: T[],
   action: (t: T) => Promise<R>,
@@ -50,6 +41,14 @@ export async function mapAsyncSequential<T, R>(
   return results;
 }
 
+/**
+ * `Array#find` for async operations where order matters.
+ * @param array The array to traverse.
+ * @param predicate An async predicate to be called on every array item. Should
+ * return a boolean indicating whether the currently element should be returned.
+ * @returns The function immediately returns the first item on which `predicate`
+ * returns `true`, or `undefined` if none matches the predicate.
+ */
 export async function findAsyncSequential<T>(
   array: T[],
   predicate: (t: T) => Promise<boolean>,
@@ -62,6 +61,21 @@ export async function findAsyncSequential<T>(
   return undefined;
 }
 
+/**
+ * Takes a message and reports it according to the severity that the user wants.
+ *
+ * - `ignore`: completely no-op
+ * - `log`: uses the `INFO` log level
+ * - `warn`: uses the `WARN` log level
+ * - `error`: uses the `ERROR` log level
+ * - `throw`: aborts the process, throws the error.
+ *
+ * Since the logger doesn't have logging level filters yet, these severities
+ * mostly just differ by their colors.
+ *
+ * @throws In addition to throwing when `reportingSeverity === "throw"`, this
+ * function also throws if `reportingSeverity` is not one of the above.
+ */
 export function reportMessage(
   message: string,
   reportingSeverity: ReportingSeverity,

package/src/markdownLinks.ts

@@ -6,41 +6,79 @@
  */
 
 import path from 'path';
+import {getContentPathList} from './dataFileUtils';
 import {aliasedSitePath} from './pathUtils';
 
+/**
+ * Content plugins have a base path and a localized path to source content from.
+ * We will look into the localized path in priority.
+ */
 export type ContentPaths = {
+  /**
+   * The absolute path to the base content directory, like `"<siteDir>/docs"`.
+   */
   contentPath: string;
+  /**
+   * The absolute path to the localized content directory, like
+   * `"<siteDir>/i18n/zh-Hans/plugin-content-docs"`.
+   */
   contentPathLocalized: string;
 };
 
+/** Data structure representing each broken Markdown link to be reported. */
 export type BrokenMarkdownLink<T extends ContentPaths> = {
+  /** Absolute path to the file containing this link. */
   filePath: string;
+  /**
+   * This is generic because it may contain extra metadata like version name,
+   * which the reporter can provide for context.
+   */
   contentPaths: T;
+  /**
+   * The content of the link, like `"./brokenFile.md"`
+   */
   link: string;
 };
 
-export type ReplaceMarkdownLinksParams<T extends ContentPaths> = {
+/**
+ * Takes a Markdown file and replaces relative file references with their URL
+ * counterparts, e.g. `[link](./intro.md)` => `[link](/docs/intro)`, preserving
+ * everything else.
+ *
+ * This method uses best effort to find a matching file. The file reference can
+ * be relative to the directory of the current file (most likely) or any of the
+ * content paths (so `/tutorials/intro.md` can be resolved as
+ * `<siteDir>/docs/tutorials/intro.md`). Links that contain the `http(s):` or
+ * `@site/` prefix will always be ignored.
+ */
+export function replaceMarkdownLinks<T extends ContentPaths>({
+  siteDir,
+  fileString,
+  filePath,
+  contentPaths,
+  sourceToPermalink,
+}: {
+  /** Absolute path to the site directory, used to resolve aliased paths. */
   siteDir: string;
+  /** The Markdown file content to be processed. */
   fileString: string;
+  /** Absolute path to the current file containing `fileString`. */
   filePath: string;
+  /** The content paths which the file reference may live in. */
   contentPaths: T;
+  /**
+   * A map from source paths to their URLs. Source paths are `@site` aliased.
+   */
   sourceToPermalink: Record<string, string>;
-};
-
-export type ReplaceMarkdownLinksReturn<T extends ContentPaths> = {
+}): {
+  /**
+   * The content with all Markdown file references replaced with their URLs.
+   * Unresolved links are left as-is.
+   */
   newContent: string;
+  /** The list of broken links,  */
   brokenMarkdownLinks: BrokenMarkdownLink<T>[];
-};
-
-export function replaceMarkdownLinks<T extends ContentPaths>({
-  siteDir,
-  fileString,
-  filePath,
-  contentPaths,
-  sourceToPermalink,
-}: ReplaceMarkdownLinksParams<T>): ReplaceMarkdownLinksReturn<T> {
-  const {contentPath, contentPathLocalized} = contentPaths;
-
+} {
   const brokenMarkdownLinks: BrokenMarkdownLink<T>[] = [];
 
   // Replace internal markdown linking (except in fenced blocks).
@@ -64,9 +102,8 @@ 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
-    // ink
-    // [doc1]: doc1.md -> we replace this doc1.md with correct link
+    // This is [Document 1](doc1.md)
+    // [doc1]: doc1.md
     const mdRegex =
       /(?:\]\(|\]:\s*)(?!https?:\/\/|@site\/)(?<filename>[^'")\]\s>]+\.mdx?)/g;
     let mdMatch = mdRegex.exec(modifiedLine);
@@ -75,10 +112,9 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
       const mdLink = mdMatch.groups!.filename!;
 
       const sourcesToTry = [
-        path.resolve(path.dirname(filePath), decodeURIComponent(mdLink)),
-        `${contentPathLocalized}/${decodeURIComponent(mdLink)}`,
-        `${contentPath}/${decodeURIComponent(mdLink)}`,
-      ];
+        path.dirname(filePath),
+        ...getContentPathList(contentPaths),
+      ].map((p) => path.join(p, decodeURIComponent(mdLink)));
 
       const aliasedSourceMatch = sourcesToTry
         .map((source) => aliasedSitePath(source, siteDir))

package/src/markdownUtils.ts

@@ -7,12 +7,25 @@
 
 import logger from '@docusaurus/logger';
 import matter from 'gray-matter';
-import {createSlugger, type Slugger} from './slugger';
+import {createSlugger, type Slugger, type SluggerOptions} from './slugger';
 
-// Input: ## Some heading {#some-heading}
-// Output: {text: "## Some heading", id: "some-heading"}
+// Some utilities for parsing Markdown content. These things are only used on
+// server-side when we infer metadata like `title` and `description` from the
+// content. Most parsing is still done in MDX through the mdx-loader.
+
+/**
+ * Parses custom ID from a heading. The ID must be composed of letters,
+ * underscores, and dashes only.
+ *
+ * @param heading e.g. `## Some heading {#some-heading}` where the last
+ * character must be `}` for the ID to be recognized
+ */
 export function parseMarkdownHeadingId(heading: string): {
+  /**
+   * The heading content sans the ID part, right-trimmed. e.g. `## Some heading`
+   */
   text: string;
+  /** The heading ID. e.g. `some-heading` */
   id?: string;
 } {
   const customHeadingIdRegex = /\s*\{#(?<id>[\w-]+)\}$/;
@@ -26,26 +39,40 @@ export function parseMarkdownHeadingId(heading: string): {
   return {text: heading, id: undefined};
 }
 
-// Hacky way of stripping out import statements from the excerpt
 // TODO: Find a better way to do so, possibly by compiling the Markdown content,
 // stripping out HTML tags and obtaining the first line.
+/**
+ * Creates an excerpt of a Markdown file. This function will:
+ *
+ * - Ignore h1 headings (setext or atx)
+ * - Ignore import/export
+ * - Ignore code blocks
+ *
+ * And for the first contentful line, it will strip away most Markdown
+ * syntax, including HTML tags, emphasis, links (keeping the text), etc.
+ */
 export function createExcerpt(fileString: string): string | undefined {
   const fileLines = fileString
-    .trimLeft()
+    .trimStart()
     // Remove Markdown alternate title
     .replace(/^[^\n]*\n[=]+/g, '')
     .split('\n');
   let inCode = false;
+  let inImport = false;
   let lastCodeFence = '';
 
   for (const fileLine of fileLines) {
+    if (fileLine === '' && inImport) {
+      inImport = false;
+    }
     // Skip empty line.
     if (!fileLine.trim()) {
       continue;
     }
 
     // Skip import/export declaration.
-    if (/^(?:import|export)\s.*/.test(fileLine)) {
+    if ((/^(?:import|export)\s.*/.test(fileLine) || inImport) && !inCode) {
+      inImport = true;
       continue;
     }
 
@@ -102,8 +129,22 @@ export function createExcerpt(fileString: string): string | undefined {
   return undefined;
 }
 
+/**
+ * Takes a raw Markdown file content, and parses the front matter using
+ * gray-matter. Worth noting that gray-matter accepts TOML and other markup
+ * languages as well.
+ *
+ * @throws Throws when gray-matter throws. e.g.:
+ * ```md
+ * ---
+ * foo: : bar
+ * ---
+ * ```
+ */
 export function parseFrontMatter(markdownFileContent: string): {
+  /** Front matter as parsed by gray-matter. */
   frontMatter: Record<string, unknown>;
+  /** The remaining content, trimmed. */
   content: string;
 } {
   const {data, content} = matter(markdownFileContent);
@@ -113,11 +154,6 @@ export function parseFrontMatter(markdownFileContent: string): {
   };
 }
 
-/**
- * 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);
@@ -125,10 +161,36 @@ function toTextContentTitle(contentTitle: string): string {
   return contentTitle;
 }
 
+type ParseMarkdownContentTitleOptions = {
+  /**
+   * If `true`, the matching title will be removed from the returned content.
+   * We can promise that at least one empty line will be left between the
+   * content before and after, but you shouldn't make too much assumption
+   * about what's left.
+   */
+  removeContentTitle?: boolean;
+};
+
+/**
+ * Takes the raw Markdown content, without front matter, and tries to find an h1
+ * title (setext or atx) to be used as metadata.
+ *
+ * It only searches until the first contentful paragraph, ignoring import/export
+ * declarations.
+ *
+ * It will try to convert markdown to reasonable text, but won't be best effort,
+ * since it's only used as a fallback when `frontMatter.title` is not provided.
+ * For now, we just unwrap inline code (``# `config.js` `` => `config.js`).
+ */
 export function parseMarkdownContentTitle(
   contentUntrimmed: string,
-  options?: {removeContentTitle?: boolean},
-): {content: string; contentTitle: string | undefined} {
+  options?: ParseMarkdownContentTitleOptions,
+): {
+  /** The content, optionally without the content title. */
+  content: string;
+  /** The title, trimmed and without the `#`. */
+  contentTitle: string | undefined;
+} {
   const removeContentTitleOption = options?.removeContentTitle ?? false;
 
   const content = contentUntrimmed.trim();
@@ -171,17 +233,28 @@ export function parseMarkdownContentTitle(
   };
 }
 
-type ParsedMarkdown = {
+/**
+ * Makes a full-round parse.
+ *
+ * @throws Throws when `parseFrontMatter` throws, usually because of invalid
+ * syntax.
+ */
+export function parseMarkdownString(
+  markdownFileContent: string,
+  options?: ParseMarkdownContentTitleOptions,
+): {
+  /** @see {@link parseFrontMatter} */
   frontMatter: Record<string, unknown>;
-  content: string;
+  /** @see {@link parseMarkdownContentTitle} */
   contentTitle: string | undefined;
+  /** @see {@link createExcerpt} */
   excerpt: string | undefined;
-};
-
-export function parseMarkdownString(
-  markdownFileContent: string,
-  options?: {removeContentTitle?: boolean},
-): ParsedMarkdown {
+  /**
+   * Content without front matter and (optionally) without title, depending on
+   * the `removeContentTitle` option.
+   */
+  content: string;
+} {
   try {
     const {frontMatter, content: contentWithoutFrontMatter} =
       parseFrontMatter(markdownFileContent);
@@ -229,11 +302,16 @@ function addHeadingId(
   return `${headingHashes}${headingText} {#${slug}}`;
 }
 
-export type WriteHeadingIDOptions = {
-  maintainCase?: boolean;
+export type WriteHeadingIDOptions = SluggerOptions & {
+  /** Overwrite existing heading IDs. */
   overwrite?: boolean;
 };
 
+/**
+ * Takes Markdown content, returns new content with heading IDs written.
+ * Respects existing IDs (unless `overwrite=true`) and never generates colliding
+ * IDs (through the slugger).
+ */
 export function writeMarkdownHeadingId(
   content: string,
   options: WriteHeadingIDOptions = {maintainCase: false, overwrite: false},

package/src/pathUtils.ts

@@ -24,7 +24,7 @@ export const isNameTooLong = (str: string): boolean =>
     ? 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)
 
-export const shortName = (str: string): string => {
+export function shortName(str: string): string {
   if (isMacOs() || isWindows()) {
     const overflowingChars = str.length - MAX_PATH_SEGMENT_CHARS;
     return str.slice(
@@ -41,7 +41,7 @@ export const shortName = (str: string): string => {
       Buffer.byteLength(strBuffer) - overflowingBytes - SPACE_FOR_APPENDING - 1,
     )
     .toString();
-};
+}
 
 /**
  * Convert Windows backslash paths to posix style paths.

package/src/slugger.ts

@@ -10,12 +10,24 @@ import GithubSlugger from 'github-slugger';
 // We create our own abstraction on top of the lib:
 // - unify usage everywhere in the codebase
 // - ability to add extra options
-export type SluggerOptions = {maintainCase?: boolean};
+export type SluggerOptions = {
+  /** Keep the headings' casing, otherwise make all lowercase. */
+  maintainCase?: boolean;
+};
 
 export type Slugger = {
+  /**
+   * Takes a Markdown heading like "Josh Cena" and sluggifies it according to
+   * GitHub semantics (in this case `josh-cena`). Stateful, because if you try
+   * to sluggify "Josh Cena" again it would return `josh-cena-1`.
+   */
   slug: (value: string, options?: SluggerOptions) => string;
 };
 
+/**
+ * A thin wrapper around github-slugger. This is a factory function that returns
+ * a stateful Slugger object.
+ */
 export function createSlugger(): Slugger {
   const githubSlugger = new GithubSlugger();
   return {