feat(blog): add LastUpdateAuthor & LastUpdateTime

packages/docusaurus-plugin-content-blog/src/blogUtils.ts

@@ -29,13 +29,16 @@ import {
 } from '@docusaurus/utils';
 import {validateBlogPostFrontMatter} from './frontMatter';
 import {type AuthorsMap, getAuthorsMap, getBlogPostAuthors} from './authors';
+import {getFileLastUpdate} from './lastUpdate';
 import type {LoadContext, ParseFrontMatter} from '@docusaurus/types';
 import type {
   PluginOptions,
   ReadingTimeFunction,
   BlogPost,
   BlogTags,
   BlogPaginated,
+  FileChange,
+  LastUpdateData,
 } from '@docusaurus/plugin-content-blog';
 import type {BlogContentPaths, BlogMarkdownLoaderOptions} from './types';
 
@@ -51,6 +54,52 @@ export function getSourceToPermalink(blogPosts: BlogPost[]): {
   );
 }
 
+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 function paginateBlogPosts({
   blogPosts,
   basePageUrl,
@@ -231,6 +280,12 @@ async function processBlogSourceFile(
 
   const aliasedSource = aliasedSitePath(blogSourceAbsolute, siteDir);
 
+  const lastUpdate = await readLastUpdateData(
+    blogSourceAbsolute,
+    options,
+    frontMatter.last_update,
+  );
+
   const draft = isDraft({frontMatter});
   const unlisted = isUnlisted({frontMatter});
 
@@ -337,6 +392,8 @@ async function processBlogSourceFile(
       authors,
       frontMatter,
       unlisted,
+      lastUpdatedAt: lastUpdate.lastUpdatedAt,
+      lastUpdatedBy: lastUpdate.lastUpdatedBy,
     },
     content,
   };

packages/docusaurus-plugin-content-blog/src/frontMatter.ts

@@ -28,6 +28,9 @@ const BlogPostFrontMatterAuthorSchema = Joi.object({
 const FrontMatterAuthorErrorMessage =
   '{{#label}} does not look like a valid blog post author. Please use an author key or an author object (with a key and/or name).';
 
+const FrontMatterLastUpdateErrorMessage =
+  '{{#label}} does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).';
+
 const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   id: Joi.string(),
   title: Joi.string().allow(''),
@@ -69,6 +72,15 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
   hide_table_of_contents: Joi.boolean(),
 
   ...FrontMatterTOCHeadingLevels,
+  last_update: Joi.object({
+    author: Joi.string(),
+    date: Joi.date().raw(),
+  })
+    .or('author', 'date')
+    .messages({
+      'object.missing': FrontMatterLastUpdateErrorMessage,
+      'object.base': FrontMatterLastUpdateErrorMessage,
+    }),
 })
   .messages({
     'deprecate.error':

packages/docusaurus-plugin-content-blog/src/lastUpdate.ts

@@ -0,0 +1,52 @@
+/**
+ * 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;
+  }
+}

packages/docusaurus-plugin-content-blog/src/options.ts

@@ -51,6 +51,8 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   authorsMapPath: 'authors.yml',
   readingTime: ({content, defaultReadingTime}) => defaultReadingTime({content}),
   sortPosts: 'descending',
+  showLastUpdateTime: false,
+  showLastUpdateAuthor: false,
 };
 
 const PluginOptionSchema = Joi.object<PluginOptions>({
@@ -134,6 +136,10 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   sortPosts: Joi.string()
     .valid('descending', 'ascending')
     .default(DEFAULT_OPTIONS.sortPosts),
+  showLastUpdateTime: Joi.bool().default(DEFAULT_OPTIONS.showLastUpdateTime),
+  showLastUpdateAuthor: Joi.bool().default(
+    DEFAULT_OPTIONS.showLastUpdateAuthor,
+  ),
 }).default(DEFAULT_OPTIONS);
 
 export function validateOptions({

packages/docusaurus-plugin-content-blog/src/plugin-content-blog.d.ts

@@ -69,6 +69,14 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     [key: string]: unknown;
   };
 
+  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;
+  };
+
   /**
    * Everything is partial/unnormalized, because front matter is always
    * preserved as-is. Default values will be applied when generating metadata
@@ -156,6 +164,8 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     toc_min_heading_level?: number;
     /** Maximum TOC heading level. Must be between 2 and 6. */
     toc_max_heading_level?: number;
+    /** Allows overriding the last updated author and/or date. */
+    last_update?: FileChange;
   };
 
   export type BlogPostFrontMatterAuthor = Author & {
@@ -180,7 +190,14 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     | BlogPostFrontMatterAuthor
     | (string | BlogPostFrontMatterAuthor)[];
 
-  export type BlogPostMetadata = {
+  export type LastUpdateData = {
+    /** A timestamp in **seconds**, directly acquired from `git log`. */
+    lastUpdatedAt?: number;
+    /** The author's name directly acquired from `git log`. */
+    lastUpdatedBy?: string;
+  };
+
+  export type BlogPostMetadata = LastUpdateData & {
     /** Path to the Markdown source, with `@site` alias. */
     readonly source: string;
     /**
@@ -421,6 +438,10 @@ yarn workspace v1.22.19image` is a collocated image path, this entry will be the
     readingTime: ReadingTimeFunctionOption;
     /** Governs the direction of blog post sorting. */
     sortPosts: 'ascending' | 'descending';
+    /**	Whether to display the last date the doc was updated. */
+    showLastUpdateTime?: boolean;
+    /** Whether to display the author who last updated the doc. */
+    showLastUpdateAuthor?: boolean;
   };
 
   /**

packages/docusaurus-theme-classic/src/theme/BlogPostItem/Header/Info/index.tsx

@@ -15,6 +15,7 @@ import {
 } from '@docusaurus/theme-common/internal';
 import type {Props} from '@theme/BlogPostItem/Header/Info';
 
+import LastUpdated from '@theme/LastUpdated';
 import styles from './styles.module.css';
 
 // Very simple pluralization: probably good enough for now
@@ -60,7 +61,8 @@ export default function BlogPostItemHeaderInfo({
   className,
 }: Props): JSX.Element {
   const {metadata} = useBlogPost();
-  const {date, readingTime} = metadata;
+  const {date, readingTime, lastUpdatedAt, lastUpdatedBy} = metadata;
+  console.log('metadata:', metadata);
 
   const dateTimeFormat = useDateTimeFormat({
     day: 'numeric',
@@ -79,6 +81,13 @@ export default function BlogPostItemHeaderInfo({
         <>
           <Spacer />
           <ReadingTime readingTime={readingTime} />
+          <Spacer />
+          {(lastUpdatedAt || lastUpdatedBy) && (
+            <LastUpdated
+              lastUpdatedAt={lastUpdatedAt}
+              lastUpdatedBy={lastUpdatedBy}
+            />
+          )}
         </>
       )}
     </div>

website/docusaurus.config.ts

@@ -441,6 +441,8 @@ export default async function createConfigAsync() {
           blog: {
             // routeBasePath: '/',
             path: 'blog',
+            showLastUpdateAuthor: true,
+            showLastUpdateTime: true,
             editUrl: ({locale, blogDirPath, blogPath}) => {
               if (locale !== defaultLocale) {
                 return `https://crowdin.com/project/docusaurus-v2/${locale}`;