@docusaurus/plugin-content-docs 0.0.0-5865 → 0.0.0-5868

package/lib/docs.js

@@ -12,42 +12,10 @@ const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
-const lastUpdate_1 = require("./lastUpdate");
+const frontMatter_1 = require("./frontMatter");
 const slug_1 = tslib_1.__importDefault(require("./slug"));
 const numberPrefix_1 = require("./numberPrefix");
-const frontMatter_1 = require("./frontMatter");
 const utils_2 = require("./sidebars/utils");
-async function readLastUpdateData(filePath, options, lastUpdateFrontMatter) {
-    const { showLastUpdateAuthor, showLastUpdateTime } = options;
-    if (showLastUpdateAuthor || showLastUpdateTime) {
-        const frontMatterTimestamp = lastUpdateFrontMatter?.date
-            ? new Date(lastUpdateFrontMatter.date).getTime() / 1000
-            : undefined;
-        if (lastUpdateFrontMatter?.author && lastUpdateFrontMatter.date) {
-            return {
-                lastUpdatedAt: frontMatterTimestamp,
-                lastUpdatedBy: lastUpdateFrontMatter.author,
-            };
-        }
-        // Use fake data in dev for faster development.
-        const fileLastUpdateData = process.env.NODE_ENV === 'production'
-            ? await (0, lastUpdate_1.getFileLastUpdate)(filePath)
-            : {
-                author: 'Author',
-                timestamp: 1539502055,
-            };
-        const { author, timestamp } = fileLastUpdateData ?? {};
-        return {
-            lastUpdatedBy: showLastUpdateAuthor
-                ? lastUpdateFrontMatter?.author ?? author
-                : undefined,
-            lastUpdatedAt: showLastUpdateTime
-                ? frontMatterTimestamp ?? timestamp
-                : undefined,
-        };
-    }
-    return {};
-}
 async function readDocFile(versionMetadata, source) {
     const contentPath = await (0, utils_1.getFolderContainingFile)((0, utils_1.getContentPathList)(versionMetadata), source);
     const filePath = path_1.default.join(contentPath, source);
@@ -77,7 +45,7 @@ async function doProcessDocMetadata({ docFile, versionMetadata, context, options
     // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true, last_update: lastUpdateFrontMatter, } = frontMatter;
-    const lastUpdate = await readLastUpdateData(filePath, options, lastUpdateFrontMatter);
+    const lastUpdate = await (0, utils_1.readLastUpdateData)(filePath, options, lastUpdateFrontMatter);
     // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
     const sourceFileNameWithoutExtension = path_1.default.basename(source, path_1.default.extname(source));
     // E.g. api/plugins/myDoc -> api/plugins; myDoc -> .

package/lib/frontMatter.d.ts

@@ -1,10 +1,5 @@
-/**
- * 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 { DocFrontMatter } from '@docusaurus/plugin-content-docs';
+export declare const DocFrontMatterSchema: import("joi").ObjectSchema<DocFrontMatter>;
 export declare function validateDocFrontMatter(frontMatter: {
     [key: string]: unknown;
 }): DocFrontMatter;

package/lib/frontMatter.js

@@ -1,19 +1,18 @@
 "use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateDocFrontMatter = exports.DocFrontMatterSchema = void 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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateDocFrontMatter = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
-const FrontMatterLastUpdateErrorMessage = '{{#label}} does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).';
 // NOTE: we don't add any default value on purpose here
 // We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
-const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
+exports.DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     id: utils_validation_1.JoiFrontMatter.string(),
     // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
     title: utils_validation_1.JoiFrontMatter.string().allow(''),
@@ -36,19 +35,11 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     pagination_next: utils_validation_1.JoiFrontMatter.string().allow(null),
     pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
     ...utils_validation_1.FrontMatterTOCHeadingLevels,
-    last_update: utils_validation_1.JoiFrontMatter.object({
-        author: utils_validation_1.JoiFrontMatter.string(),
-        date: utils_validation_1.JoiFrontMatter.date().raw(),
-    })
-        .or('author', 'date')
-        .messages({
-        'object.missing': FrontMatterLastUpdateErrorMessage,
-        'object.base': FrontMatterLastUpdateErrorMessage,
-    }),
+    last_update: utils_validation_1.FrontMatterLastUpdateSchema,
 })
     .unknown()
     .concat(utils_validation_1.ContentVisibilitySchema);
 function validateDocFrontMatter(frontMatter) {
-    return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);
+    return (0, utils_validation_1.validateFrontMatter)(frontMatter, exports.DocFrontMatterSchema);
 }
 exports.validateDocFrontMatter = validateDocFrontMatter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-5865",
+  "version": "0.0.0-5868",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,13 +35,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5865",
-    "@docusaurus/logger": "0.0.0-5865",
-    "@docusaurus/mdx-loader": "0.0.0-5865",
-    "@docusaurus/module-type-aliases": "0.0.0-5865",
-    "@docusaurus/types": "0.0.0-5865",
-    "@docusaurus/utils": "0.0.0-5865",
-    "@docusaurus/utils-validation": "0.0.0-5865",
+    "@docusaurus/core": "0.0.0-5868",
+    "@docusaurus/logger": "0.0.0-5868",
+    "@docusaurus/mdx-loader": "0.0.0-5868",
+    "@docusaurus/module-type-aliases": "0.0.0-5868",
+    "@docusaurus/types": "0.0.0-5868",
+    "@docusaurus/utils": "0.0.0-5868",
+    "@docusaurus/utils-validation": "0.0.0-5868",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
@@ -65,5 +65,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "0ce2912136d682daeb3abe9d1284a49f9c011efa"
+  "gitHead": "82bedf4154c3c66e27563a6735763c5b08518820"
 }

package/src/docs.ts

@@ -20,12 +20,11 @@ import {
   normalizeFrontMatterTags,
   isUnlisted,
   isDraft,
+  readLastUpdateData,
 } from '@docusaurus/utils';
-
-import {getFileLastUpdate} from './lastUpdate';
+import {validateDocFrontMatter} from './frontMatter';
 import getSlug from './slug';
 import {stripPathNumberPrefixes} from './numberPrefix';
-import {validateDocFrontMatter} from './frontMatter';
 import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
 import type {
   MetadataOptions,
@@ -34,61 +33,13 @@ import type {
   DocMetadataBase,
   DocMetadata,
   PropNavigationLink,
-  LastUpdateData,
   VersionMetadata,
   LoadedVersion,
-  FileChange,
 } from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
 import type {SidebarsUtils} from './sidebars/utils';
 import type {DocFile} from './types';
 
-type LastUpdateOptions = Pick<
-  PluginOptions,
-  'showLastUpdateAuthor' | 'showLastUpdateTime'
->;
-
-async function readLastUpdateData(
-  filePath: string,
-  options: LastUpdateOptions,
-  lastUpdateFrontMatter: FileChange | undefined,
-): Promise<LastUpdateData> {
-  const {showLastUpdateAuthor, showLastUpdateTime} = options;
-  if (showLastUpdateAuthor || showLastUpdateTime) {
-    const frontMatterTimestamp = lastUpdateFrontMatter?.date
-      ? new Date(lastUpdateFrontMatter.date).getTime() / 1000
-      : undefined;
-
-    if (lastUpdateFrontMatter?.author && lastUpdateFrontMatter.date) {
-      return {
-        lastUpdatedAt: frontMatterTimestamp,
-        lastUpdatedBy: lastUpdateFrontMatter.author,
-      };
-    }
-
-    // Use fake data in dev for faster development.
-    const fileLastUpdateData =
-      process.env.NODE_ENV === 'production'
-        ? await getFileLastUpdate(filePath)
-        : {
-            author: 'Author',
-            timestamp: 1539502055,
-          };
-    const {author, timestamp} = fileLastUpdateData ?? {};
-
-    return {
-      lastUpdatedBy: showLastUpdateAuthor
-        ? lastUpdateFrontMatter?.author ?? author
-        : undefined,
-      lastUpdatedAt: showLastUpdateTime
-        ? frontMatterTimestamp ?? timestamp
-        : undefined,
-    };
-  }
-
-  return {};
-}
-
 export async function readDocFile(
   versionMetadata: Pick<
     VersionMetadata,

package/src/frontMatter.ts

@@ -4,7 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
 import {
   JoiFrontMatter as Joi, // Custom instance for front matter
   URISchema,
@@ -12,17 +11,15 @@ import {
   FrontMatterTOCHeadingLevels,
   validateFrontMatter,
   ContentVisibilitySchema,
+  FrontMatterLastUpdateSchema,
 } from '@docusaurus/utils-validation';
 import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 
-const FrontMatterLastUpdateErrorMessage =
-  '{{#label}} does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).';
-
 // NOTE: we don't add any default value on purpose here
 // We don't want default values to magically appear in doc metadata and props
 // While the user did not provide those values explicitly
 // We use default values in code instead
-const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
+export const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   id: Joi.string(),
   // See https://github.com/facebook/docusaurus/issues/4591#issuecomment-822372398
   title: Joi.string().allow(''),
@@ -45,15 +42,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   pagination_next: Joi.string().allow(null),
   pagination_prev: Joi.string().allow(null),
   ...FrontMatterTOCHeadingLevels,
-  last_update: Joi.object({
-    author: Joi.string(),
-    date: Joi.date().raw(),
-  })
-    .or('author', 'date')
-    .messages({
-      'object.missing': FrontMatterLastUpdateErrorMessage,
-      'object.base': FrontMatterLastUpdateErrorMessage,
-    }),
+  last_update: FrontMatterLastUpdateSchema,
 })
   .unknown()
   .concat(ContentVisibilitySchema);

package/src/plugin-content-docs.d.ts

@@ -16,6 +16,7 @@ declare module '@docusaurus/plugin-content-docs' {
     TagsListItem,
     TagModule,
     Tag,
+    FrontMatterLastUpdate,
   } from '@docusaurus/utils';
   import type {Plugin, LoadContext} from '@docusaurus/types';
   import type {Overwrite, Required} from 'utility-types';
@@ -24,14 +25,6 @@ declare module '@docusaurus/plugin-content-docs' {
     image?: string;
   };
 
-  export type FileChange = {
-    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;
-  };
-
   /**
    * Custom callback for parsing number prefixes from file/folder names.
    */
@@ -93,9 +86,9 @@ declare module '@docusaurus/plugin-content-docs' {
      */
     editLocalizedFiles: boolean;
     /**	Whether to display the last date the doc was updated. */
-    showLastUpdateTime?: boolean;
+    showLastUpdateTime: boolean;
     /** Whether to display the author who last updated the doc. */
-    showLastUpdateAuthor?: boolean;
+    showLastUpdateAuthor: boolean;
     /**
      * Custom parsing logic to extract number prefixes from file names. Use
      * `false` to disable this behavior and leave the docs untouched, and `true`
@@ -401,7 +394,7 @@ declare module '@docusaurus/plugin-content-docs' {
     /** Should this doc be accessible but hidden in production builds? */
     unlisted?: boolean;
     /** Allows overriding the last updated author and/or date. */
-    last_update?: FileChange;
+    last_update?: FrontMatterLastUpdate;
   };
 
   export type LastUpdateData = {

package/lib/lastUpdate.d.ts

@@ -1,10 +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 getFileLastUpdate(filePath: string): Promise<{
-    timestamp: number;
-    author: string;
-} | null>;

package/lib/lastUpdate.js

@@ -1,47 +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.getFileLastUpdate = void 0;
-const tslib_1 = require("tslib");
-const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
-const utils_1 = require("@docusaurus/utils");
-let showedGitRequirementError = false;
-let showedFileNotTrackedError = false;
-async function getFileLastUpdate(filePath) {
-    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 (0, utils_1.getFileCommitDate)(filePath, {
-            age: 'newest',
-            includeAuthor: true,
-        });
-        return { timestamp: result.timestamp, author: result.author };
-    }
-    catch (err) {
-        if (err instanceof utils_1.GitNotFoundError) {
-            if (!showedGitRequirementError) {
-                logger_1.default.warn('Sorry, the docs plugin last update options require Git.');
-                showedGitRequirementError = true;
-            }
-        }
-        else if (err instanceof utils_1.FileNotTrackedError) {
-            if (!showedFileNotTrackedError) {
-                logger_1.default.warn('Cannot infer the update date for some files, as they are not tracked by git.');
-                showedFileNotTrackedError = true;
-            }
-        }
-        else {
-            logger_1.default.warn(err);
-        }
-        return null;
-    }
-}
-exports.getFileLastUpdate = getFileLastUpdate;

package/src/lastUpdate.ts

@@ -1,52 +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 logger from '@docusaurus/logger';
-import {
-  getFileCommitDate,
-  FileNotTrackedError,
-  GitNotFoundError,
-} from '@docusaurus/utils';
-
-let showedGitRequirementError = false;
-let showedFileNotTrackedError = false;
-
-export async function getFileLastUpdate(
-  filePath: string,
-): Promise<{timestamp: number; author: string} | 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 {timestamp: result.timestamp, author: result.author};
-  } catch (err) {
-    if (err instanceof GitNotFoundError) {
-      if (!showedGitRequirementError) {
-        logger.warn('Sorry, the docs plugin 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 {
-      logger.warn(err);
-    }
-    return null;
-  }
-}