@docusaurus/utils 3.1.0 → 3.2.0

package/src/lastUpdateUtils.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {
+  FileNotTrackedError,
+  GitNotFoundError,
+  getFileCommitDate,
+} from './gitUtils';
+import type {PluginOptions} from '@docusaurus/types';
+
+export type LastUpdateData = {
+  /** A timestamp in **milliseconds**, usually read from `git log` */
+  lastUpdatedAt?: number;
+  /** The author's name, usually coming from `git log` */
+  lastUpdatedBy?: string;
+};
+
+let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
+
+export async function getGitLastUpdate(
+  filePath: string,
+): Promise<LastUpdateData | null> {
+  if (!filePath) {
+    return null;
+  }
+
+  // Wrap in try/catch in case the shell commands fail
+  // (e.g. project doesn't use Git, etc).
+  try {
+    const result = await getFileCommitDate(filePath, {
+      age: 'newest',
+      includeAuthor: true,
+    });
+
+    return {lastUpdatedAt: result.timestamp, lastUpdatedBy: result.author};
+  } catch (err) {
+    if (err instanceof GitNotFoundError) {
+      if (!showedGitRequirementError) {
+        logger.warn('Sorry, the last update options require Git.');
+        showedGitRequirementError = true;
+      }
+    } else if (err instanceof FileNotTrackedError) {
+      if (!showedFileNotTrackedError) {
+        logger.warn(
+          'Cannot infer the update date for some files, as they are not tracked by git.',
+        );
+        showedFileNotTrackedError = true;
+      }
+    } else {
+      throw new Error(
+        `An error occurred when trying to get the last update date`,
+        {cause: err},
+      );
+    }
+    return null;
+  }
+}
+
+export const LAST_UPDATE_FALLBACK: LastUpdateData = {
+  lastUpdatedAt: 1539502055000,
+  lastUpdatedBy: 'Author',
+};
+
+export async function getLastUpdate(
+  filePath: string,
+): Promise<LastUpdateData | null> {
+  if (process.env.NODE_ENV !== 'production') {
+    // Use fake data in dev/test for faster development.
+    return LAST_UPDATE_FALLBACK;
+  }
+  return getGitLastUpdate(filePath);
+}
+
+type LastUpdateOptions = Pick<
+  PluginOptions,
+  'showLastUpdateAuthor' | 'showLastUpdateTime'
+>;
+
+export type FrontMatterLastUpdate = {
+  author?: string;
+  /**
+   * Date can be any
+   * [parsable date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse).
+   */
+  date?: Date | string;
+};
+
+export async function readLastUpdateData(
+  filePath: string,
+  options: LastUpdateOptions,
+  lastUpdateFrontMatter: FrontMatterLastUpdate | undefined,
+): Promise<LastUpdateData> {
+  const {showLastUpdateAuthor, showLastUpdateTime} = options;
+
+  if (!showLastUpdateAuthor && !showLastUpdateTime) {
+    return {};
+  }
+
+  const frontMatterAuthor = lastUpdateFrontMatter?.author;
+  const frontMatterTimestamp = lastUpdateFrontMatter?.date
+    ? new Date(lastUpdateFrontMatter.date).getTime()
+    : undefined;
+
+  // We try to minimize git last update calls
+  // We call it at most once
+  // If all the data is provided as front matter, we do not call it
+  const getLastUpdateMemoized = _.memoize(() => getLastUpdate(filePath));
+  const getLastUpdateBy = () =>
+    getLastUpdateMemoized().then((update) => update?.lastUpdatedBy);
+  const getLastUpdateAt = () =>
+    getLastUpdateMemoized().then((update) => update?.lastUpdatedAt);
+
+  const lastUpdatedBy = showLastUpdateAuthor
+    ? frontMatterAuthor ?? (await getLastUpdateBy())
+    : undefined;
+
+  const lastUpdatedAt = showLastUpdateTime
+    ? frontMatterTimestamp ?? (await getLastUpdateAt())
+    : undefined;
+
+  return {
+    lastUpdatedBy,
+    lastUpdatedAt,
+  };
+}

package/src/markdownUtils.ts

@@ -70,9 +70,9 @@ export function escapeMarkdownHeadingIds(content: string): string {
 export function unwrapMdxCodeBlocks(content: string): string {
   // We only support 3/4 backticks on purpose, should be good enough
   const regexp3 =
-    /(?<begin>^|\n)```mdx-code-block\n(?<children>.*?)\n```(?<end>\n|$)/gs;
+    /(?<begin>^|\r?\n)```(?<spaces>\x20*)mdx-code-block\r?\n(?<children>.*?)\r?\n```(?<end>\r?\n|$)/gs;
   const regexp4 =
-    /(?<begin>^|\n)````mdx-code-block\n(?<children>.*?)\n````(?<end>\n|$)/gs;
+    /(?<begin>^|\r?\n)````(?<spaces>\x20*)mdx-code-block\r?\n(?<children>.*?)\r?\n````(?<end>\r?\n|$)/gs;
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const replacer = (substring: string, ...args: any[]) => {

package/src/pathUtils.ts

@@ -92,6 +92,20 @@ export function aliasedSitePath(filePath: string, siteDir: string): string {
   return `@site/${relativePath}`;
 }
 
+/**
+ * Converts back the aliased site path (starting with "@site/...") to a relative path
+ *
+ * TODO method this is a workaround, we shouldn't need to alias/un-alias paths
+ *  we should refactor the codebase to not have aliased site paths everywhere
+ *  We probably only need aliasing for client-only paths required by Webpack
+ */
+export function aliasedSitePathToRelativePath(filePath: string): string {
+  if (filePath.startsWith('@site/')) {
+    return filePath.replace('@site/', '');
+  }
+  throw new Error(`Unexpected, filePath is not site-aliased: ${filePath}`);
+}
+
 /**
  * When you have a path like C:\X\Y
  * It is not safe to use directly when generating code

package/src/routeUtils.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 type {RouteConfig} from '@docusaurus/types';
+
+/**
+ * Recursively flatten routes and only return the "leaf routes"
+ * Parent routes are filtered out
+ */
+export function flattenRoutes(routeConfig: RouteConfig[]): RouteConfig[] {
+  function flatten(route: RouteConfig): RouteConfig[] {
+    return route.routes ? route.routes.flatMap(flatten) : [route];
+  }
+  return routeConfig.flatMap(flatten);
+}

package/src/urlUtils.ts

@@ -6,7 +6,6 @@
  */
 
 import resolvePathnameUnsafe from 'resolve-pathname';
-import {addPrefix, addSuffix, removeSuffix} from './jsUtils';
 
 /**
  * Much like `path.join`, but much better. Takes an array of URL segments, and
@@ -232,22 +231,6 @@ export function resolvePathname(to: string, from?: string): string {
   return resolvePathnameUnsafe(to, from);
 }
 
-/** Appends a leading slash to `str`, if one doesn't exist. */
-export function addLeadingSlash(str: string): string {
-  return addPrefix(str, '/');
-}
-
-// TODO deduplicate: also present in @docusaurus/utils-common
-/** Appends a trailing slash to `str`, if one doesn't exist. */
-export function addTrailingSlash(str: string): string {
-  return addSuffix(str, '/');
-}
-
-/** Removes the trailing slash from `str`. */
-export function removeTrailingSlash(str: string): string {
-  return removeSuffix(str, '/');
-}
-
 /** Constructs an SSH URL that can be used to push to GitHub. */
 export function buildSshUrl(
   githubHost: string,