@docusaurus/plugin-content-docs 0.0.0-5077 → 0.0.0-5084

package/lib/docs.d.ts

@@ -8,8 +8,7 @@ import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, DocMetadataB
 import type { LoadContext } from '@docusaurus/types';
 import type { SidebarsUtils } from './sidebars/utils';
 import type { DocFile } from './types';
-declare type LastUpdateOptions = Pick<PluginOptions, 'showLastUpdateAuthor' | 'showLastUpdateTime'>;
-export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string, options: LastUpdateOptions): Promise<DocFile>;
+export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string): Promise<DocFile>;
 export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
 export declare type DocEnv = 'production' | 'development';
 export declare function processDocMetadata(args: {
@@ -18,7 +17,7 @@ export declare function processDocMetadata(args: {
     context: LoadContext;
     options: MetadataOptions;
     env: DocEnv;
-}): DocMetadataBase;
+}): Promise<DocMetadataBase>;
 export declare function addDocNavigation(docsBase: DocMetadataBase[], sidebarsUtils: SidebarsUtils, sidebarFilePath: string): LoadedVersion['docs'];
 /**
  * The "main doc" is the "version entry point"
@@ -44,4 +43,3 @@ export declare function createDocsByIdIndex<Doc extends {
 }>(docs: Doc[]): {
     [docId: string]: Doc;
 };
-export {};

package/lib/docs.js

@@ -18,9 +18,18 @@ const constants_1 = require("./constants");
 const numberPrefix_1 = require("./numberPrefix");
 const frontMatter_1 = require("./frontMatter");
 const utils_2 = require("./sidebars/utils");
-async function readLastUpdateData(filePath, options) {
+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)
@@ -28,24 +37,23 @@ async function readLastUpdateData(filePath, options) {
                 author: 'Author',
                 timestamp: 1539502055,
             };
-        if (fileLastUpdateData) {
-            const { author, timestamp } = fileLastUpdateData;
-            return {
-                lastUpdatedAt: showLastUpdateTime ? timestamp : undefined,
-                lastUpdatedBy: showLastUpdateAuthor ? author : undefined,
-            };
-        }
+        const { author, timestamp } = fileLastUpdateData ?? {};
+        return {
+            lastUpdatedBy: showLastUpdateAuthor
+                ? lastUpdateFrontMatter?.author ?? author
+                : undefined,
+            lastUpdatedAt: showLastUpdateTime
+                ? frontMatterTimestamp ?? timestamp
+                : undefined,
+        };
     }
     return {};
 }
-async function readDocFile(versionMetadata, source, options) {
+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);
-    const [content, lastUpdate] = await Promise.all([
-        fs_extra_1.default.readFile(filePath, 'utf-8'),
-        readLastUpdateData(filePath, options),
-    ]);
-    return { source, content, lastUpdate, contentPath, filePath };
+    const content = await fs_extra_1.default.readFile(filePath, 'utf-8');
+    return { source, content, contentPath, filePath };
 }
 exports.readDocFile = readDocFile;
 async function readVersionDocs(versionMetadata, options) {
@@ -53,15 +61,15 @@ async function readVersionDocs(versionMetadata, options) {
         cwd: versionMetadata.contentPath,
         ignore: options.exclude,
     });
-    return Promise.all(sources.map((source) => readDocFile(versionMetadata, source, options)));
+    return Promise.all(sources.map((source) => readDocFile(versionMetadata, source)));
 }
 exports.readVersionDocs = readVersionDocs;
 /** Docs with draft front matter are only considered draft in production. */
 function isDraftForEnvironment({ env, frontMatter, }) {
     return (env === 'production' && frontMatter.draft) ?? false;
 }
-function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
-    const { source, content, lastUpdate, contentPath, filePath } = docFile;
+async function doProcessDocMetadata({ docFile, versionMetadata, context, options, env, }) {
+    const { source, content, contentPath, filePath } = docFile;
     const { siteDir, i18n } = context;
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
     const frontMatter = (0, frontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
@@ -69,7 +77,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, env,
     // Strip number prefixes by default
     // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
-    parse_number_prefixes: parseNumberPrefixes = true, } = frontMatter;
+    parse_number_prefixes: parseNumberPrefixes = true, last_update: lastUpdateFrontMatter, } = frontMatter;
+    const lastUpdate = await 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.js

@@ -8,6 +8,7 @@
 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
@@ -36,6 +37,15 @@ const DocFrontMatterSchema = utils_validation_1.JoiFrontMatter.object({
     pagination_prev: utils_validation_1.JoiFrontMatter.string().allow(null),
     draft: utils_validation_1.JoiFrontMatter.boolean(),
     ...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,
+    }),
 }).unknown();
 function validateDocFrontMatter(frontMatter) {
     return (0, utils_validation_1.validateFrontMatter)(frontMatter, DocFrontMatterSchema);

package/lib/index.js

@@ -50,9 +50,7 @@ async function pluginContentDocs(context, options) {
                 .command(command)
                 .arguments('<version>')
                 .description(commandDescription)
-                .action((version) => {
-                (0, cli_1.cliDocsVersionCommand)(version, options, context);
-            });
+                .action((version) => (0, cli_1.cliDocsVersionCommand)(version, options, context));
         },
         getTranslationFiles({ content }) {
             return (0, translations_1.getLoadedContentTranslationFiles)(content);

package/lib/types.d.ts

@@ -5,14 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { BrokenMarkdownLink, Tag } from '@docusaurus/utils';
-import type { VersionMetadata, LastUpdateData, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
+import type { VersionMetadata, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';
 export declare type DocFile = {
     contentPath: string;
     filePath: string;
     source: string;
     content: string;
-    lastUpdate: LastUpdateData;
 };
 export declare type SourceToPermalink = {
     [source: string]: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-5077",
+  "version": "0.0.0-5084",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -25,13 +25,13 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5077",
-    "@docusaurus/logger": "0.0.0-5077",
-    "@docusaurus/mdx-loader": "0.0.0-5077",
-    "@docusaurus/module-type-aliases": "0.0.0-5077",
-    "@docusaurus/types": "0.0.0-5077",
-    "@docusaurus/utils": "0.0.0-5077",
-    "@docusaurus/utils-validation": "0.0.0-5077",
+    "@docusaurus/core": "0.0.0-5084",
+    "@docusaurus/logger": "0.0.0-5084",
+    "@docusaurus/mdx-loader": "0.0.0-5084",
+    "@docusaurus/module-type-aliases": "0.0.0-5084",
+    "@docusaurus/types": "0.0.0-5084",
+    "@docusaurus/utils": "0.0.0-5084",
+    "@docusaurus/utils-validation": "0.0.0-5084",
     "@types/react-router-config": "^5.0.6",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.1.0",
@@ -59,5 +59,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "c94e9b3454e0518e25d5a8cdf85278a491125b19"
+  "gitHead": "4db4f1b0fa7df2b6307358354d1f6743de22e310"
 }

package/src/docs.ts

@@ -37,6 +37,7 @@ import type {
   VersionMetadata,
   DocFrontMatter,
   LoadedVersion,
+  FileChange,
 } from '@docusaurus/plugin-content-docs';
 import type {LoadContext} from '@docusaurus/types';
 import type {SidebarsUtils} from './sidebars/utils';
@@ -50,9 +51,21 @@ type LastUpdateOptions = Pick<
 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'
@@ -61,14 +74,16 @@ async function readLastUpdateData(
             author: 'Author',
             timestamp: 1539502055,
           };
-
-    if (fileLastUpdateData) {
-      const {author, timestamp} = fileLastUpdateData;
-      return {
-        lastUpdatedAt: showLastUpdateTime ? timestamp : undefined,
-        lastUpdatedBy: showLastUpdateAuthor ? author : undefined,
-      };
-    }
+    const {author, timestamp} = fileLastUpdateData ?? {};
+
+    return {
+      lastUpdatedBy: showLastUpdateAuthor
+        ? lastUpdateFrontMatter?.author ?? author
+        : undefined,
+      lastUpdatedAt: showLastUpdateTime
+        ? frontMatterTimestamp ?? timestamp
+        : undefined,
+    };
   }
 
   return {};
@@ -80,7 +95,6 @@ export async function readDocFile(
     'contentPath' | 'contentPathLocalized'
   >,
   source: string,
-  options: LastUpdateOptions,
 ): Promise<DocFile> {
   const contentPath = await getFolderContainingFile(
     getContentPathList(versionMetadata),
@@ -89,11 +103,8 @@ export async function readDocFile(
 
   const filePath = path.join(contentPath, source);
 
-  const [content, lastUpdate] = await Promise.all([
-    fs.readFile(filePath, 'utf-8'),
-    readLastUpdateData(filePath, options),
-  ]);
-  return {source, content, lastUpdate, contentPath, filePath};
+  const content = await fs.readFile(filePath, 'utf-8');
+  return {source, content, contentPath, filePath};
 }
 
 export async function readVersionDocs(
@@ -108,7 +119,7 @@ export async function readVersionDocs(
     ignore: options.exclude,
   });
   return Promise.all(
-    sources.map((source) => readDocFile(versionMetadata, source, options)),
+    sources.map((source) => readDocFile(versionMetadata, source)),
   );
 }
 
@@ -125,7 +136,7 @@ function isDraftForEnvironment({
   return (env === 'production' && frontMatter.draft) ?? false;
 }
 
-function doProcessDocMetadata({
+async function doProcessDocMetadata({
   docFile,
   versionMetadata,
   context,
@@ -137,8 +148,8 @@ function doProcessDocMetadata({
   context: LoadContext;
   options: MetadataOptions;
   env: DocEnv;
-}): DocMetadataBase {
-  const {source, content, lastUpdate, contentPath, filePath} = docFile;
+}): Promise<DocMetadataBase> {
+  const {source, content, contentPath, filePath} = docFile;
   const {siteDir, i18n} = context;
 
   const {
@@ -155,8 +166,15 @@ function doProcessDocMetadata({
     // (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,
+  );
+
   // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
   const sourceFileNameWithoutExtension = path.basename(
     source,
@@ -287,7 +305,7 @@ export function processDocMetadata(args: {
   context: LoadContext;
   options: MetadataOptions;
   env: DocEnv;
-}): DocMetadataBase {
+}): Promise<DocMetadataBase> {
   try {
     return doProcessDocMetadata(args);
   } catch (err) {

package/src/frontMatter.ts

@@ -14,6 +14,9 @@ import {
 } 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
@@ -42,6 +45,15 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   pagination_prev: Joi.string().allow(null),
   draft: Joi.boolean(),
   ...FrontMatterTOCHeadingLevels,
+  last_update: Joi.object({
+    author: Joi.string(),
+    date: Joi.date().raw(),
+  })
+    .or('author', 'date')
+    .messages({
+      'object.missing': FrontMatterLastUpdateErrorMessage,
+      'object.base': FrontMatterLastUpdateErrorMessage,
+    }),
 }).unknown();
 
 export function validateDocFrontMatter(frontMatter: {

package/src/index.ts

@@ -100,9 +100,9 @@ export default async function pluginContentDocs(
         .command(command)
         .arguments('<version>')
         .description(commandDescription)
-        .action((version: unknown) => {
-          cliDocsVersionCommand(version, options, context);
-        });
+        .action((version: unknown) =>
+          cliDocsVersionCommand(version, options, context),
+        );
     },
 
     getTranslationFiles({content}) {

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

@@ -23,6 +23,14 @@ 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.
    */
@@ -371,6 +379,8 @@ declare module '@docusaurus/plugin-content-docs' {
     pagination_prev?: string | null;
     /** Should this doc be excluded from production builds? */
     draft?: boolean;
+    /** Allows overriding the last updated author and/or date. */
+    last_update?: FileChange;
   };
 
   export type LastUpdateData = {

package/src/types.ts

@@ -8,7 +8,6 @@
 import type {BrokenMarkdownLink, Tag} from '@docusaurus/utils';
 import type {
   VersionMetadata,
-  LastUpdateData,
   LoadedVersion,
   CategoryGeneratedIndexMetadata,
 } from '@docusaurus/plugin-content-docs';
@@ -19,7 +18,6 @@ export type DocFile = {
   filePath: string; // /!\ may be localized
   source: string;
   content: string;
-  lastUpdate: LastUpdateData;
 };
 
 export type SourceToPermalink = {