feat(content-docs): last_update front matter (#7461)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com> Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
2025-07-31 07:18:59 +02:00 · 2022-06-01 10:27:58 -04:00 · 2022-06-01 10:27:58 -04:00 · 4f26a1911a
commit 4f26a1911a
parent a469ae3d63
15 changed files with 499 additions and 36 deletions
--- a/packages/docusaurus-plugin-content-docs/src/tests/fixtures/simple-site/docs/customLastUpdate.md
+++ b/packages/docusaurus-plugin-content-docs/src/tests/fixtures/simple-site/docs/customLastUpdate.md
@ -0,0 +1,8 @@
+---
+title: Custom Last Update
+last_update:
+  author: Custom Author
+  date: 1/1/2000
+---
+
+Custom last update
--- a/packages/docusaurus-plugin-content-docs/src/tests/fixtures/simple-site/docs/lastUpdateAuthorOnly.md
+++ b/packages/docusaurus-plugin-content-docs/src/tests/fixtures/simple-site/docs/lastUpdateAuthorOnly.md
@ -0,0 +1,7 @@
+---
+title: Last Update Author Only
+last_update:
+  author: Custom Author
+---
+
+Only custom author, so it will still use the date from Git
--- a/packages/docusaurus-plugin-content-docs/src/tests/fixtures/simple-site/docs/lastUpdateDateOnly.md
+++ b/packages/docusaurus-plugin-content-docs/src/tests/fixtures/simple-site/docs/lastUpdateDateOnly.md
@ -0,0 +1,7 @@
+---
+title: Last Update Date Only
+last_update:
+  date: 1/1/2000
+---
+
+Only custom date, so it will still use the author from Git
--- a/packages/docusaurus-plugin-content-docs/src/tests/snapshots/docs.test.ts.snap
+++ b/packages/docusaurus-plugin-content-docs/src/tests/snapshots/docs.test.ts.snap
@ -3,13 +3,24 @@
 exports[`simple site custom pagination 1`] = `
 {
  "pagination": [
+    {
+      "id": "customLastUpdate",
+      "next": {
+        "permalink": "/docs/doc with space",
+        "title": "Hoo hoo, if this path tricks you...",
+      },
+      "prev": undefined,
+    },
    {
      "id": "doc with space",
      "next": {
        "permalink": "/docs/doc-draft",
        "title": "doc-draft",
      },
-      "prev": undefined,
+      "prev": {
+        "permalink": "/docs/customLastUpdate",
+        "title": "Custom Last Update",
+      },
    },
    {
      "id": "doc-draft",
@ -63,14 +74,36 @@ exports[`simple site custom pagination 1`] = `
    {
      "id": "ipsum",
      "next": {
-        "permalink": "/docs/lorem",
-        "title": "lorem",
+        "permalink": "/docs/lastUpdateAuthorOnly",
+        "title": "Last Update Author Only",
      },
      "prev": {
        "permalink": "/docs/",
        "title": "Hello sidebar_label",
      },
    },
+    {
+      "id": "lastUpdateAuthorOnly",
+      "next": {
+        "permalink": "/docs/lastUpdateDateOnly",
+        "title": "Last Update Date Only",
+      },
+      "prev": {
+        "permalink": "/docs/ipsum",
+        "title": "ipsum",
+      },
+    },
+    {
+      "id": "lastUpdateDateOnly",
+      "next": {
+        "permalink": "/docs/lorem",
+        "title": "lorem",
+      },
+      "prev": {
+        "permalink": "/docs/lastUpdateAuthorOnly",
+        "title": "Last Update Author Only",
+      },
+    },
    {
      "id": "lorem",
      "next": {
@ -78,8 +111,8 @@ exports[`simple site custom pagination 1`] = `
        "title": "rootAbsoluteSlug",
      },
      "prev": {
-        "permalink": "/docs/ipsum",
-        "title": "ipsum",
+        "permalink": "/docs/lastUpdateDateOnly",
+        "title": "Last Update Date Only",
      },
    },
    {
@ -170,6 +203,10 @@ exports[`simple site custom pagination 1`] = `
  ],
  "sidebars": {
    "defaultSidebar": [
+      {
+        "id": "customLastUpdate",
+        "type": "doc",
+      },
      {
        "id": "doc with space",
        "type": "doc",
@ -208,6 +245,14 @@ exports[`simple site custom pagination 1`] = `
        "id": "ipsum",
        "type": "doc",
      },
+      {
+        "id": "lastUpdateAuthorOnly",
+        "type": "doc",
+      },
+      {
+        "id": "lastUpdateDateOnly",
+        "type": "doc",
+      },
      {
        "id": "lorem",
        "type": "doc",
--- a/packages/docusaurus-plugin-content-docs/src/tests/snapshots/index.test.ts.snap
+++ b/packages/docusaurus-plugin-content-docs/src/tests/snapshots/index.test.ts.snap
@ -22,6 +22,7 @@ These sidebar document ids do not exist:
 - nonExistent

 Available document ids are:
+- customLastUpdate
 - doc with space
 - doc-draft
 - foo/bar
@ -29,6 +30,8 @@ Available document ids are:
 - headingAsTitle
 - hello
 - ipsum
+- lastUpdateAuthorOnly
+- lastUpdateDateOnly
 - lorem
 - rootAbsoluteSlug
 - rootRelativeSlug
@ -267,6 +270,11 @@ exports[`simple website content 5`] = `
      "versions": [
        {
          "docs": [
+            {
+              "id": "customLastUpdate",
+              "path": "/docs/customLastUpdate",
+              "sidebar": undefined,
+            },
            {
              "id": "doc with space",
              "path": "/docs/doc with space",
@ -302,6 +310,16 @@ exports[`simple website content 5`] = `
              "path": "/docs/ipsum",
              "sidebar": undefined,
            },
+            {
+              "id": "lastUpdateAuthorOnly",
+              "path": "/docs/lastUpdateAuthorOnly",
+              "sidebar": undefined,
+            },
+            {
+              "id": "lastUpdateDateOnly",
+              "path": "/docs/lastUpdateDateOnly",
+              "sidebar": undefined,
+            },
            {
              "id": "lorem",
              "path": "/docs/lorem",
@ -390,6 +408,26 @@ exports[`simple website content: data 1`] = `
      "permalink": "/docs/rootAbsoluteSlug"
    }
  }
+}",
+  "site-docs-custom-last-update-md-b8d.json": "{
+  "unversionedId": "customLastUpdate",
+  "id": "customLastUpdate",
+  "title": "Custom Last Update",
+  "description": "Custom last update",
+  "source": "@site/docs/customLastUpdate.md",
+  "sourceDirName": ".",
+  "slug": "/customLastUpdate",
+  "permalink": "/docs/customLastUpdate",
+  "draft": false,
+  "tags": [],
+  "version": "current",
+  "frontMatter": {
+    "title": "Custom Last Update",
+    "last_update": {
+      "author": "Custom Author",
+      "date": "1/1/2000"
+    }
+  }
 }",
  "site-docs-doc-draft-md-584.json": "{
  "unversionedId": "doc-draft",
@ -563,6 +601,44 @@ exports[`simple website content: data 1`] = `
  "frontMatter": {
    "custom_edit_url": null
  }
+}",
+  "site-docs-last-update-author-only-md-352.json": "{
+  "unversionedId": "lastUpdateAuthorOnly",
+  "id": "lastUpdateAuthorOnly",
+  "title": "Last Update Author Only",
+  "description": "Only custom author, so it will still use the date from Git",
+  "source": "@site/docs/lastUpdateAuthorOnly.md",
+  "sourceDirName": ".",
+  "slug": "/lastUpdateAuthorOnly",
+  "permalink": "/docs/lastUpdateAuthorOnly",
+  "draft": false,
+  "tags": [],
+  "version": "current",
+  "frontMatter": {
+    "title": "Last Update Author Only",
+    "last_update": {
+      "author": "Custom Author"
+    }
+  }
+}",
+  "site-docs-last-update-date-only-md-987.json": "{
+  "unversionedId": "lastUpdateDateOnly",
+  "id": "lastUpdateDateOnly",
+  "title": "Last Update Date Only",
+  "description": "Only custom date, so it will still use the author from Git",
+  "source": "@site/docs/lastUpdateDateOnly.md",
+  "sourceDirName": ".",
+  "slug": "/lastUpdateDateOnly",
+  "permalink": "/docs/lastUpdateDateOnly",
+  "draft": false,
+  "tags": [],
+  "version": "current",
+  "frontMatter": {
+    "title": "Last Update Date Only",
+    "last_update": {
+      "date": "1/1/2000"
+    }
+  }
 }",
  "site-docs-lorem-md-b27.json": "{
  "unversionedId": "lorem",
@ -924,6 +1000,11 @@ exports[`simple website content: data 1`] = `
    ]
  },
  "docs": {
+    "customLastUpdate": {
+      "id": "customLastUpdate",
+      "title": "Custom Last Update",
+      "description": "Custom last update"
+    },
    "doc with space": {
      "id": "doc with space",
      "title": "Hoo hoo, if this path tricks you...",
@ -963,6 +1044,16 @@ exports[`simple website content: data 1`] = `
      "title": "ipsum",
      "description": "Lorem ipsum."
    },
+    "lastUpdateAuthorOnly": {
+      "id": "lastUpdateAuthorOnly",
+      "title": "Last Update Author Only",
+      "description": "Only custom author, so it will still use the date from Git"
+    },
+    "lastUpdateDateOnly": {
+      "id": "lastUpdateDateOnly",
+      "title": "Last Update Date Only",
+      "description": "Only custom date, so it will still use the author from Git"
+    },
    "lorem": {
      "id": "lorem",
      "title": "lorem",
@ -1026,6 +1117,11 @@ exports[`simple website content: global data 1`] = `
      "versions": [
        {
          "docs": [
+            {
+              "id": "customLastUpdate",
+              "path": "/docs/customLastUpdate",
+              "sidebar": undefined,
+            },
            {
              "id": "doc with space",
              "path": "/docs/doc with space",
@ -1061,6 +1157,16 @@ exports[`simple website content: global data 1`] = `
              "path": "/docs/ipsum",
              "sidebar": undefined,
            },
+            {
+              "id": "lastUpdateAuthorOnly",
+              "path": "/docs/lastUpdateAuthorOnly",
+              "sidebar": undefined,
+            },
+            {
+              "id": "lastUpdateDateOnly",
+              "path": "/docs/lastUpdateDateOnly",
+              "sidebar": undefined,
+            },
            {
              "id": "lorem",
              "path": "/docs/lorem",
@ -1202,6 +1308,14 @@ exports[`simple website content: route config 1`] = `
        "path": "/docs/category/slugs",
        "sidebar": "docs",
      },
+      {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": {
+          "content": "@site/docs/customLastUpdate.md",
+        },
+        "path": "/docs/customLastUpdate",
+      },
      {
        "component": "@theme/DocItem",
        "exact": true,
@ -1262,6 +1376,22 @@ exports[`simple website content: route config 1`] = `
        },
        "path": "/docs/ipsum",
      },
+      {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": {
+          "content": "@site/docs/lastUpdateAuthorOnly.md",
+        },
+        "path": "/docs/lastUpdateAuthorOnly",
+      },
+      {
+        "component": "@theme/DocItem",
+        "exact": true,
+        "modules": {
+          "content": "@site/docs/lastUpdateDateOnly.md",
+        },
+        "path": "/docs/lastUpdateDateOnly",
+      },
      {
        "component": "@theme/DocItem",
        "exact": true,
--- a/packages/docusaurus-plugin-content-docs/src/tests/docs.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/docs.test.ts
@ -57,7 +57,6 @@ ${markdown}
  return {
    source,
    content,
-    lastUpdate: {},
    contentPath: 'docs',
    filePath: source,
  };
@ -79,7 +78,7 @@ function createTestUtils({
  env = 'production',
 }: TestUtilsArg) {
  async function readDoc(docFileSource: string) {
-    return readDocFile(versionMetadata, docFileSource, options);
+    return readDocFile(versionMetadata, docFileSource);
  }
  async function processDocFile(docFileArg: DocFile | string) {
    const docFile: DocFile =
@ -119,7 +118,7 @@ function createTestUtils({

  async function testSlug(docFileSource: string, expectedPermalink: string) {
    const docFile = await readDoc(docFileSource);
-    const metadata = processDocMetadata({
+    const metadata = await processDocMetadata({
      docFile,
      versionMetadata,
      context,
@ -137,14 +136,16 @@ function createTestUtils({
    }[];
    sidebars: Sidebars;
  }> {
-    const rawDocs = docFiles.map((docFile) =>
-      processDocMetadata({
-        docFile,
-        versionMetadata,
-        context,
-        options,
-        env: 'production',
-      }),
+    const rawDocs = await Promise.all(
+      docFiles.map(async (docFile) =>
+        processDocMetadata({
+          docFile,
+          versionMetadata,
+          context,
+          options,
+          env: 'production',
+        }),
+      ),
    );
    const sidebars = await loadSidebars(versionMetadata.sidebarFilePath, {
      sidebarItemsGenerator: ({defaultSidebarItemsGenerator, ...args}) =>
@ -230,6 +231,9 @@ describe('simple site', () => {
        'headingAsTitle.md',
        'doc with space.md',
        'doc-draft.md',
+        'customLastUpdate.md',
+        'lastUpdateAuthorOnly.md',
+        'lastUpdateDateOnly.md',
        'foo/bar.md',
        'foo/baz.md',
        'slugs/absoluteSlug.md',
@ -481,6 +485,164 @@ describe('simple site', () => {
    });
  });

+  it('docs with last_update front matter', async () => {
+    const {siteDir, context, options, currentVersion, createTestUtilsPartial} =
+      await loadSite({
+        options: {
+          showLastUpdateAuthor: true,
+          showLastUpdateTime: true,
+        },
+      });
+
+    const testUtilsLocal = createTestUtilsPartial({
+      siteDir,
+      context,
+      options,
+      versionMetadata: currentVersion,
+    });
+
+    await testUtilsLocal.testMeta('customLastUpdate.md', {
+      version: 'current',
+      id: 'customLastUpdate',
+      unversionedId: 'customLastUpdate',
+      sourceDirName: '.',
+      permalink: '/docs/customLastUpdate',
+      slug: '/customLastUpdate',
+      title: 'Custom Last Update',
+      description: 'Custom last update',
+      frontMatter: {
+        last_update: {
+          author: 'Custom Author',
+          date: '1/1/2000',
+        },
+        title: 'Custom Last Update',
+      },
+      lastUpdatedAt: new Date('1/1/2000').getTime() / 1000,
+      formattedLastUpdatedAt: '1/1/2000',
+      lastUpdatedBy: 'Custom Author',
+      sidebarPosition: undefined,
+      tags: [],
+    });
+  });
+
+  it('docs with only last_update author front matter', async () => {
+    const {siteDir, context, options, currentVersion, createTestUtilsPartial} =
+      await loadSite({
+        options: {
+          showLastUpdateAuthor: true,
+          showLastUpdateTime: true,
+        },
+      });
+
+    const testUtilsLocal = createTestUtilsPartial({
+      siteDir,
+      context,
+      options,
+      versionMetadata: currentVersion,
+    });
+
+    await testUtilsLocal.testMeta('lastUpdateAuthorOnly.md', {
+      version: 'current',
+      id: 'lastUpdateAuthorOnly',
+      unversionedId: 'lastUpdateAuthorOnly',
+      sourceDirName: '.',
+      permalink: '/docs/lastUpdateAuthorOnly',
+      slug: '/lastUpdateAuthorOnly',
+      title: 'Last Update Author Only',
+      description: 'Only custom author, so it will still use the date from Git',
+      frontMatter: {
+        last_update: {
+          author: 'Custom Author',
+        },
+        title: 'Last Update Author Only',
+      },
+      lastUpdatedAt: 1539502055,
+      formattedLastUpdatedAt: '10/14/2018',
+      lastUpdatedBy: 'Custom Author',
+      sidebarPosition: undefined,
+      tags: [],
+    });
+  });
+
+  it('docs with only last_update date front matter', async () => {
+    const {siteDir, context, options, currentVersion, createTestUtilsPartial} =
+      await loadSite({
+        options: {
+          showLastUpdateAuthor: true,
+          showLastUpdateTime: true,
+        },
+      });
+
+    const testUtilsLocal = createTestUtilsPartial({
+      siteDir,
+      context,
+      options,
+      versionMetadata: currentVersion,
+    });
+
+    await testUtilsLocal.testMeta('lastUpdateDateOnly.md', {
+      version: 'current',
+      id: 'lastUpdateDateOnly',
+      unversionedId: 'lastUpdateDateOnly',
+      sourceDirName: '.',
+      permalink: '/docs/lastUpdateDateOnly',
+      slug: '/lastUpdateDateOnly',
+      title: 'Last Update Date Only',
+      description: 'Only custom date, so it will still use the author from Git',
+      frontMatter: {
+        last_update: {
+          date: '1/1/2000',
+        },
+        title: 'Last Update Date Only',
+      },
+      lastUpdatedAt: new Date('1/1/2000').getTime() / 1000,
+      formattedLastUpdatedAt: '1/1/2000',
+      lastUpdatedBy: 'Author',
+      sidebarPosition: undefined,
+      tags: [],
+    });
+  });
+
+  it('docs with last_update front matter disabled', async () => {
+    const {siteDir, context, options, currentVersion, createTestUtilsPartial} =
+      await loadSite({
+        options: {
+          showLastUpdateAuthor: false,
+          showLastUpdateTime: false,
+        },
+      });
+
+    const testUtilsLocal = createTestUtilsPartial({
+      siteDir,
+      context,
+      options,
+      versionMetadata: currentVersion,
+    });
+
+    await testUtilsLocal.testMeta('customLastUpdate.md', {
+      version: 'current',
+      id: 'customLastUpdate',
+      unversionedId: 'customLastUpdate',
+      sourceDirName: '.',
+      permalink: '/docs/customLastUpdate',
+      slug: '/customLastUpdate',
+      title: 'Custom Last Update',
+      description: 'Custom last update',
+      frontMatter: {
+        last_update: {
+          author: 'Custom Author',
+          date: '1/1/2000',
+        },
+        title: 'Custom Last Update',
+      },
+      lastUpdatedAt: undefined,
+      formattedLastUpdatedAt: undefined,
+      lastUpdatedBy: undefined,
+      sidebarPosition: undefined,
+      tags: [],
+    });
+  });
+
  it('docs with slugs', async () => {
    const {defaultTestUtils} = await loadSite();

--- a/packages/docusaurus-plugin-content-docs/src/tests/frontMatter.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/tests/frontMatter.test.ts
@ -396,3 +396,52 @@ describe('validateDocFrontMatter draft', () => {
    ],
  });
 });
+
+describe('validateDocFrontMatter last_update', () => {
+  testField({
+    prefix: 'last_update',
+    validFrontMatters: [
+      {last_update: undefined},
+      {last_update: {author: 'test author', date: undefined}},
+      {last_update: {author: undefined, date: '1/1/2000'}},
+      {last_update: {author: undefined, date: new Date('1/1/2000')}},
+      {last_update: {author: 'test author', date: '1/1/2000'}},
+      {last_update: {author: 'test author', date: '1995-12-17T03:24:00'}},
+      {last_update: {author: undefined, date: 'December 17, 1995 03:24:00'}},
+    ],
+    invalidFrontMatters: [
+      [
+        {last_update: null},
+        'does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).',
+      ],
+      [
+        {last_update: {}},
+        'does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).',
+      ],
+      [
+        {last_update: ''},
+        'does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).',
+      ],
+      [
+        {last_update: {invalid: 'key'}},
+        'does not look like a valid front matter FileChange object. Please use a FileChange object (with an author and/or date).',
+      ],
+      [
+        {last_update: {author: 'test author', date: 'I am not a date :('}},
+        'must be a valid date',
+      ],
+      [
+        {last_update: {author: 'test author', date: '2011-10-45'}},
+        'must be a valid date',
+      ],
+      [
+        {last_update: {author: 'test author', date: '2011-0-10'}},
+        'must be a valid date',
+      ],
+      [
+        {last_update: {author: 'test author', date: ''}},
+        'must be a valid date',
+      ],
+    ],
+  });
+});