feat(content-docs,content-blog,theme-classic): add created_at front matter and creation metadata (AI-assisted)

Fixes #5691

Expose creation date and author from VCS git history, alongside existing last_updated feature, via new created_at front matter field.

- Add readCreationData() with memoization, mirroring readLastUpdateData
- Add FrontMatterCreationSchema for validation
- Add showCreatedTime / showCreatedBy plugin options (default false)
- Include createdAt/createdBy in doc and blog metadata
- Render creation info in theme LastUpdated component
- Include createdAt in route metadata for SSG cache

Author: Weza Mwiwa

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

@@ -23,6 +23,7 @@ import {
   isUnlisted,
   isDraft,
   readLastUpdateData,
+  readCreationData,
   normalizeTags,
   aliasedSitePathToRelativePath,
 } from '@docusaurus/utils';
@@ -260,6 +261,13 @@ async function processBlogSourceFile(
     vcs,
   );
 
+  const creation = await readCreationData(
+    blogSourceAbsolute,
+    options,
+    frontMatter.created_at,
+    vcs,
+  );
+
   const draft = isDraft({frontMatter});
   const unlisted = isUnlisted({frontMatter});
 
@@ -379,6 +387,8 @@ async function processBlogSourceFile(
       unlisted,
       lastUpdatedAt: lastUpdate.lastUpdatedAt,
       lastUpdatedBy: lastUpdate.lastUpdatedBy,
+      createdAt: creation.createdAt,
+      createdBy: creation.createdBy,
     },
     content,
   };

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

@@ -9,6 +9,7 @@
 import {
   ContentVisibilitySchema,
   FrontMatterLastUpdateSchema,
+  FrontMatterCreationSchema,
   FrontMatterTOCHeadingLevels,
   FrontMatterTagsSchema,
   JoiFrontMatter as Joi, // Custom instance for front matter
@@ -76,6 +77,7 @@ const BlogFrontMatterSchema = Joi.object<BlogPostFrontMatter>({
 
   ...FrontMatterTOCHeadingLevels,
   last_update: FrontMatterLastUpdateSchema,
+  created_at: FrontMatterCreationSchema,
 })
   .messages({
     'deprecate.error':

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

@@ -69,6 +69,8 @@ export const DEFAULT_OPTIONS: PluginOptions = {
   sortPosts: 'descending',
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
+  showCreatedTime: false,
+  showCreatedBy: false,
   processBlogPosts: async () => undefined,
   tags: undefined,
   authorsBasePath: 'authors',
@@ -227,6 +229,8 @@ const PluginOptionSchema = Joi.object<PluginOptions>({
   showLastUpdateAuthor: Joi.bool().default(
     DEFAULT_OPTIONS.showLastUpdateAuthor,
   ),
+  showCreatedTime: Joi.bool().default(DEFAULT_OPTIONS.showCreatedTime),
+  showCreatedBy: Joi.bool().default(DEFAULT_OPTIONS.showCreatedBy),
   processBlogPosts: Joi.function()
     .optional()
     .default(() => DEFAULT_OPTIONS.processBlogPosts),

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

@@ -12,7 +12,9 @@ declare module '@docusaurus/plugin-content-blog' {
     FrontMatterTag,
     TagMetadata,
     LastUpdateData,
+    CreationData,
     FrontMatterLastUpdate,
+    FrontMatterCreation,
     TagsPluginOptions,
   } from '@docusaurus/utils';
   import type {
@@ -236,6 +238,8 @@ declare module '@docusaurus/plugin-content-blog' {
     toc_max_heading_level?: number;
     /** Allows overriding the last updated author and/or date. */
     last_update?: FrontMatterLastUpdate;
+    /** Allows overriding the creation author and/or date. */
+    created_at?: FrontMatterCreation;
   };
 
   export type BlogPostFrontMatterAuthor = AuthorAttributes & {
@@ -260,61 +264,62 @@ declare module '@docusaurus/plugin-content-blog' {
     | BlogPostFrontMatterAuthor
     | (string | BlogPostFrontMatterAuthor)[];
 
-  export type BlogPostMetadata = LastUpdateData & {
-    /** Path to the Markdown source, with `@site` alias. */
-    readonly source: string;
-    /**
-     * Used to generate the page h1 heading, tab title, and pagination title.
-     */
-    readonly title: string;
-    /**
-     * The publish date of the post. On client side, this will be serialized
-     * into a string.
-     */
-    readonly date: Date;
-    /** Full link including base URL. */
-    readonly permalink: string;
-    /**
-     * Description used in the meta. Could be an empty string (empty content)
-     */
-    readonly description: string;
-    /**
-     * Absolute URL to the editing page of the post. Undefined if the post
-     * shouldn't be edited.
-     */
-    readonly editUrl?: string;
-    /**
-     * Reading time in minutes calculated based on word count.
-     */
-    readonly readingTime?: number;
-    /**
-     * Whether the truncate marker exists in the post's content.
-     */
-    readonly hasTruncateMarker: boolean;
-    /**
-     * Used in pagination. Generated after the other metadata, so not readonly.
-     * Content is just a subset of another post's metadata.
-     */
-    nextItem?: {readonly title: string; readonly permalink: string};
-    /**
-     * Used in pagination. Generated after the other metadata, so not readonly.
-     * Content is just a subset of another post's metadata.
-     */
-    prevItem?: {readonly title: string; readonly permalink: string};
-    /**
-     * Author metadata, normalized. Should be used in joint with
-     * `assets.authorsImageUrls` on client side.
-     */
-    readonly authors: Author[];
-    /** Front matter, as-is. */
-    readonly frontMatter: BlogPostFrontMatter & {[key: string]: unknown};
-    /** Tags, normalized. */
-    readonly tags: TagMetadata[];
-    /**
-     * Marks the post as unlisted and visibly hides it unless directly accessed.
-     */
-    readonly unlisted: boolean;
-  };
+  export type BlogPostMetadata = LastUpdateData &
+    CreationData & {
+      /** Path to the Markdown source, with `@site` alias. */
+      readonly source: string;
+      /**
+       * Used to generate the page h1 heading, tab title, and pagination title.
+       */
+      readonly title: string;
+      /**
+       * The publish date of the post. On client side, this will be serialized
+       * into a string.
+       */
+      readonly date: Date;
+      /** Full link including base URL. */
+      readonly permalink: string;
+      /**
+       * Description used in the meta. Could be an empty string (empty content)
+       */
+      readonly description: string;
+      /**
+       * Absolute URL to the editing page of the post. Undefined if the post
+       * shouldn't be edited.
+       */
+      readonly editUrl?: string;
+      /**
+       * Reading time in minutes calculated based on word count.
+       */
+      readonly readingTime?: number;
+      /**
+       * Whether the truncate marker exists in the post's content.
+       */
+      readonly hasTruncateMarker: boolean;
+      /**
+       * Used in pagination. Generated after the other metadata, so not readonly.
+       * Content is just a subset of another post's metadata.
+       */
+      nextItem?: {readonly title: string; readonly permalink: string};
+      /**
+       * Used in pagination. Generated after the other metadata, so not readonly.
+       * Content is just a subset of another post's metadata.
+       */
+      prevItem?: {readonly title: string; readonly permalink: string};
+      /**
+       * Author metadata, normalized. Should be used in joint with
+       * `assets.authorsImageUrls` on client side.
+       */
+      readonly authors: Author[];
+      /** Front matter, as-is. */
+      readonly frontMatter: BlogPostFrontMatter & {[key: string]: unknown};
+      /** Tags, normalized. */
+      readonly tags: TagMetadata[];
+      /**
+       * Marks the post as unlisted and visibly hides it unless directly accessed.
+       */
+      readonly unlisted: boolean;
+    };
   /**
    * @returns The edit URL that's directly plugged into metadata.
    */
@@ -524,6 +529,10 @@ declare module '@docusaurus/plugin-content-blog' {
       showLastUpdateTime: boolean;
       /** Whether to display the author who last updated the blog post. */
       showLastUpdateAuthor: boolean;
+      /** Whether to display the creation date of the blog post. */
+      showCreatedTime: boolean;
+      /** Whether to display the author who created the blog post. */
+      showCreatedBy: boolean;
       /** An optional function which can be used to transform blog posts
        *  (filter, modify, delete, etc...).
        */

packages/docusaurus-plugin-content-docs/src/docs.ts

@@ -20,6 +20,7 @@ import {
   isUnlisted,
   isDraft,
   readLastUpdateData,
+  readCreationData,
   normalizeTags,
 } from '@docusaurus/utils';
 import {validateDocFrontMatter} from './frontMatter';
@@ -63,7 +64,12 @@ export async function readVersionDocs(
   versionMetadata: VersionMetadata,
   options: Pick<
     PluginOptions,
-    'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'
+    | 'include'
+    | 'exclude'
+    | 'showLastUpdateAuthor'
+    | 'showLastUpdateTime'
+    | 'showCreatedTime'
+    | 'showCreatedBy'
   >,
 ): Promise<DocFile[]> {
   const sources = await Globby(options.include, {
@@ -120,6 +126,7 @@ async function doProcessDocMetadata({
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true,
     last_update: lastUpdateFrontMatter,
+    created_at: creationFrontMatter,
   } = frontMatter;
 
   const lastUpdate = await readLastUpdateData(
@@ -129,6 +136,13 @@ async function doProcessDocMetadata({
     vcs,
   );
 
+  const creation = await readCreationData(
+    filePath,
+    options,
+    creationFrontMatter,
+    vcs,
+  );
+
   // E.g. api/plugins/myDoc -> myDoc; myDoc -> myDoc
   const sourceFileNameWithoutExtension = path.basename(
     source,
@@ -240,6 +254,8 @@ async function doProcessDocMetadata({
     version: versionMetadata.versionName,
     lastUpdatedBy: lastUpdate.lastUpdatedBy,
     lastUpdatedAt: lastUpdate.lastUpdatedAt,
+    createdBy: creation.createdBy,
+    createdAt: creation.createdAt,
     sidebarPosition,
     frontMatter,
   };

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

@@ -14,6 +14,7 @@ import {
   validateFrontMatter,
   ContentVisibilitySchema,
   FrontMatterLastUpdateSchema,
+  FrontMatterCreationSchema,
 } from '@docusaurus/utils-validation';
 import type {DocFrontMatter} from '@docusaurus/plugin-content-docs';
 
@@ -46,6 +47,7 @@ export const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   pagination_prev: Joi.string().allow(null),
   ...FrontMatterTOCHeadingLevels,
   last_update: FrontMatterLastUpdateSchema,
+  created_at: FrontMatterCreationSchema,
 })
   .unknown()
   .concat(ContentVisibilitySchema);

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

@@ -46,6 +46,8 @@ export const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'> = {
   beforeDefaultRehypePlugins: [],
   showLastUpdateTime: false,
   showLastUpdateAuthor: false,
+  showCreatedTime: false,
+  showCreatedBy: false,
   admonitions: true,
   includeCurrentVersion: true,
   disableVersioning: false,
@@ -137,6 +139,8 @@ const OptionsSchema = Joi.object<PluginOptions>({
   showLastUpdateAuthor: Joi.bool().default(
     DEFAULT_OPTIONS.showLastUpdateAuthor,
   ),
+  showCreatedTime: Joi.bool().default(DEFAULT_OPTIONS.showCreatedTime),
+  showCreatedBy: Joi.bool().default(DEFAULT_OPTIONS.showCreatedBy),
   includeCurrentVersion: Joi.bool().default(
     DEFAULT_OPTIONS.includeCurrentVersion,
   ),