feat(content-docs): new "created" metadata #7588

dpang314 · 2022-06-09T14:44:10Z

Pre-flight checklist

I have read the Contributing Guidelines on pull requests.
If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This feature allows displaying the date that documentation was created. It uses Git history, but can be overridden through front matter. It addresses the second half of #5691.

Sometimes the wording is a bit awkward, since last update is a noun, but create isn't, but I used create/created for consistency. creation fits better grammatically in a few spots, but I don't know if that would be preferable if it breaks consistency.

Test Plan

Added unit tests for front matter configurations, including:

create front matter undefined
Author undefined but date valid
Author valid but date undefined
Invalid date strings
Both valid with varying date string formats

Created doc unit tests

Front matter overrides Git history
Front matter with only author uses Git history for date
Front matter with only date uses Git history for author
Front matter is not shown when config disables it

Dogfooding

Created new page with create set with front matter
Create time/author generated by Git history can be seen on the other dogfooding pages

Test links

Deploy preview: https://deploy-preview-7588--docusaurus-2.netlify.app/
Dogfooding page: https://deploy-preview-7588--docusaurus-2.netlify.app/tests/docs/doc-with-create/
Dogfooding page with create from Git history: https://deploy-preview-7588--docusaurus-2.netlify.app/tests/docs/
Documentation: https://deploy-preview-7588--docusaurus-2.netlify.app/docs/api/plugins/@docusaurus/plugin-content-docs/

Related issues/PRs

#5691

netlify · 2022-06-09T14:50:27Z

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`99ded9d`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/62bd69fa3bedbb00090c1bc2
😎 Deploy Preview	https://deploy-preview-7588--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

github-actions · 2022-06-09T14:50:57Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟢 90	🟢 100	🟢 100	🟢 100	🟢 90	Report
/docs/installation	🟠 82	🟢 99	🟢 100	🟢 100	🟢 90	Report

Josh-Cena

Implementation is nice, tests are first-class, but a lot of duplicated code that has best be cleaned up before progressing. I also can't remember my motivation for this feature in the first place.

Josh-Cena · 2022-06-17T10:09:23Z

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

+let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
+
+export async function getFileCreate(


Let's merge this file with getFileLastUpdate? There's a lot of duplicated code here. getFileCreate is also not a nice name; maybe getFileCreateInfo... 🤔

Josh-Cena · 2022-06-17T10:12:16Z

website/docs/api/plugins/plugin-content-docs.md

+| `showCreateAuthor` | `boolean` | `false` | Whether to display the author who created the doc. |
+| `showCreateTime` | `boolean` | `false` | Whether to display the date the doc was created. |


It's been close to a year and I don't even wholly recall my motivation for this feature...😅 Do we want it as an out-of-the-box feature, or only provide the metadata and wait for users who swizzled it to discover it? (Not a nice thing to do) I don't have a compelling use-case apart from telling two sets of documentation apart (which one is "legacy" and which one is "current"). We could use also use versioning for that purpose, though. I would need to think of a better use-case. Eventually we need to address #6218, which requires much more metadata than this.

I can’t think of a very good use-case either. I thought there was a reason that I didn’t think of 😅. Should I continue working on this feature? I am happy to close the pull request if there is no strong reason for keeping it.

Given it's not too complex, opt-in, and may give additional flexibility by exposing the creation date, I think we can keep working on this.

The other possibility for users would be to use another flexible API (like createFrontMatter? #5568) so that they can create this created metadata themselves through some callback.

Up to you, I'm fine merging this PR once ready

Got it! I'll finish this up then look into the other metadata APIs.

then look into the other metadata APIs.

what do you mean? 😅

then look into the other metadata APIs.

Never mind, I was misinterpreting something. Sorry for confusion.

slorber

Thanks 👍

Overall that looks like a very good start, just have some concerns added in comments.

Although I see how it may be useful for some users, I was wondering how users plan to use this exactly?

It looks to me like we implement a feature without a very concrete use case in mind 😅

Would you use this feature on your own doc sites?

But that's fine, the implementation is not too complex and it's optional so I'm ok to add this 👍

slorber · 2022-06-17T09:58:31Z

packages/docusaurus-theme-classic/src/theme/DocItemFooter/index.tsx

-            lastUpdatedBy={lastUpdatedBy}
-          />
-        )}
+        <div>


we don't want extra divs if both things are false.

It should never lead to <div></div><div></div> for example

slorber · 2022-06-17T10:00:33Z

packages/docusaurus-theme-classic/src/theme/Created/index.tsx

+        }}>
+        {'Created{atDate}{byUser}'}
+      </Translate>
+      {process.env.NODE_ENV === 'development' && (


wonder if this dev message shouldn't be deduplicated between created/updated cases? We'll potentially display it twice?

One potential issue with having only one message is that if a user sets created with front matter, but not for last_update, then only last_update will be simulated, while created will use the actual value in development. The dev message will still appear, but there isn't a way to tell that only last_update was simulated. Is this fine?

slorber · 2022-06-17T10:01:31Z

packages/docusaurus-theme-classic/src/theme/Created/index.tsx

+  createdBy,
+}: Props): JSX.Element {
+  return (
+    <span className={ThemeClassNames.common.lastUpdated}>


Created a dedicated themeClassName: user should be able to target each one independently with custom CSS

slorber · 2022-06-17T10:04:51Z

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

@@ -381,6 +385,8 @@ declare module '@docusaurus/plugin-content-docs' {
    draft?: boolean;
    /** Allows overriding the last updated author and/or date. */
    last_update?: FileChange;
+    /** Allows overriding the created author and/or date. */
+    create?: FileChange;


this name looks a bit weird, but it is consistent with "last_update" 🤪 may be good enough for now?

But maybe we want to use "created" immediately instead, and rename "last_update" to "last_updated" later? (breaking change)

Starting from scratch, is "create" the better name?

I think that using "creation" would work well as it is a noun and fits well in existing function names e.g. getFileCreation. This would keep it grammatically consistent with last_update as well.

slorber · 2022-06-17T10:09:15Z

packages/docusaurus-theme-classic/src/theme/Created/index.tsx

+import {ThemeClassNames} from '@docusaurus/theme-common';
+import type {Props} from '@theme/Created';
+
+function CreatedAtDate({


do we want to share some code across created/updated components?

That feels like duplication, but at the same time, we probably want granularity when swizzling, and avoid creating a weird abstraction? 🤷‍♂️

Since most of the elements have specific ids and/or descriptions, I think that sharing code would probably not be worth it.

slorber · 2022-06-17T10:11:56Z

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

@@ -89,6 +91,47 @@ async function readLastUpdateData(
  return {};
 }

+type CreateOptions = Pick<PluginOptions, 'showCreateAuthor' | 'showCreateTime'>;
+
+async function readCreateData(


also feels a bit duplicated, wonder if an abstraction could make sense?

slorber · 2022-06-17T10:13:42Z

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

+let showedGitRequirementError = false;
+let showedFileNotTrackedError = false;
+
+export async function getFileCreate(


Wouldn't it make sense to group getFileLastUpdate + getFileCreate into the same file?

cc @Josh-Cena I thought we had something like gitUtils here in the past

slorber · 2022-06-17T10:15:23Z

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

+  // Wrap in try/catch in case the shell commands fail
+  // (e.g. project doesn't use Git, etc).
+  try {
+    const result = getFileCommitDate(filePath, {


is this diff command efficient?

it looks like, but didn't run it on a large site / history to see the potential impact

slorber · 2022-06-17T10:16:07Z

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

+  testField({
+    prefix: 'create',
+    validFrontMatters: [
+      {last_update: undefined},


looks like a typo: you used last_update instead of create?

slorber · 2022-06-17T10:17:47Z

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

+    });
+  });
+
+  it('docs with create front matter disabled', async () => {


docs with showCreate options disabled?

forresst

Proposal for the good translation into French from now on

forresst · 2022-06-30T09:28:11Z

packages/docusaurus-theme-translations/locales/fr/theme-common.json

@@ -32,6 +32,9 @@
  "theme.common.editThisPage": "Éditer cette page",
  "theme.common.headingLinkTitle": "Lien direct vers le titre",
  "theme.common.skipToMainContent": "Aller au contenu principal",
+  "theme.created.atDate": " on {date}",


Suggested change

"theme.created.atDate": " on {date}",

"theme.created.atDate": " le {date}",

Proposal for the good translation into French from now on

forresst · 2022-06-30T09:28:34Z

packages/docusaurus-theme-translations/locales/fr/theme-common.json

@@ -32,6 +32,9 @@
  "theme.common.editThisPage": "Éditer cette page",
  "theme.common.headingLinkTitle": "Lien direct vers le titre",
  "theme.common.skipToMainContent": "Aller au contenu principal",
+  "theme.created.atDate": " on {date}",
+  "theme.created.byUser": " by {user}",


Suggested change

"theme.created.byUser": " by {user}",

"theme.created.byUser": " par {user}",

Proposal for the good translation into French from now on

forresst · 2022-06-30T09:29:19Z

packages/docusaurus-theme-translations/locales/fr/theme-common.json

@@ -32,6 +32,9 @@
  "theme.common.editThisPage": "Éditer cette page",
  "theme.common.headingLinkTitle": "Lien direct vers le titre",
  "theme.common.skipToMainContent": "Aller au contenu principal",
+  "theme.created.atDate": " on {date}",
+  "theme.created.byUser": " by {user}",
+  "theme.created.createdAtBy": "Created{atDate}{byUser}",


Suggested change

"theme.created.createdAtBy": "Created{atDate}{byUser}",

"theme.created.createdAtBy": "Créé{atDate}{byUser}",

Proposal for the good translation into French from now on

slorber · 2022-08-09T10:56:54Z

@dpang314 do you want to follow-up on this? Otherwise I'll complete your work and move on

dpang314 · 2022-08-16T15:22:27Z

@slorber I think that all the issues have been addressed, but I wanted to confirm the best way to handle this issue.

slorber · 2022-08-16T16:05:42Z

sorry missed the commits, will review later ;)

dpang314 added 10 commits June 7, 2022 23:13

feat(content-docs): created metadata

da8b341

docs: add create options documentation

78dd9f4

feat(theme-classic): created component

a3214dc

test: dogfooding

f1b79bd

test: change format to match other pages

ea92be5

fix: translation ids

441d52c

fix: add translation placeholders

80b3baf

refactor: remove unnecessary div

00b5d56

refactor: move type

3c549ae

refactor: update JSDoc

f466367

dpang314 requested review from slorber, lex111 and Josh-Cena as code owners June 9, 2022 14:44

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 9, 2022

Josh-Cena added the pr: new feature This PR adds a new API or behavior. label Jun 9, 2022

Josh-Cena changed the title ~~feat(content-docs): created-metadata~~ feat(content-docs): new "created" metadata Jun 9, 2022

Josh-Cena reviewed Jun 17, 2022

View reviewed changes

slorber requested changes Jun 17, 2022

View reviewed changes

dpang314 added 8 commits June 22, 2022 20:51

avoid empty divs

71960d8

fix test names

7f35c5a

fix: valid front matter tests

040291d

refactor: group getFileCreate and getFileLastUpdate

4d47153

fix: avoid duplicated dev message

a1aecd3

refactor: rename create to creation

eee92e4

test: fix names for getFileCreation tests

746d6a5

refactor: merge readLastUpdateData and readCreationData

99ded9d

forresst reviewed Jun 30, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(content-docs): new "created" metadata #7588

feat(content-docs): new "created" metadata #7588

dpang314 commented Jun 9, 2022 •

edited

Loading

netlify bot commented Jun 9, 2022 •

edited

Loading

github-actions bot commented Jun 9, 2022 •

edited

Loading

Josh-Cena left a comment

Josh-Cena Jun 17, 2022

Josh-Cena Jun 17, 2022

dpang314 Jun 18, 2022

slorber Jun 22, 2022 •

edited

Loading

dpang314 Jun 22, 2022

slorber Jun 23, 2022

dpang314 Jun 26, 2022

slorber left a comment

slorber Jun 17, 2022

slorber Jun 17, 2022

dpang314 Jun 30, 2022 •

edited

Loading

slorber Jun 17, 2022

slorber Jun 17, 2022

dpang314 Jun 30, 2022

slorber Jun 17, 2022

dpang314 Aug 16, 2022

slorber Jun 17, 2022

slorber Jun 17, 2022

slorber Jun 17, 2022

slorber Jun 17, 2022

slorber Jun 17, 2022

forresst left a comment

forresst Jun 30, 2022

forresst Jun 30, 2022

forresst Jun 30, 2022

slorber commented Aug 9, 2022

dpang314 commented Aug 16, 2022

slorber commented Aug 16, 2022

		\| `showCreateAuthor` \| `boolean` \| `false` \| Whether to display the author who created the doc. \|
		\| `showCreateTime` \| `boolean` \| `false` \| Whether to display the date the doc was created. \|

	"theme.created.atDate": " on {date}",
	"theme.created.atDate": " le {date}",

	"theme.created.byUser": " by {user}",
	"theme.created.byUser": " par {user}",

	"theme.created.createdAtBy": "Created{atDate}{byUser}",
	"theme.created.createdAtBy": "Créé{atDate}{byUser}",

feat(content-docs): new "created" metadata #7588

Are you sure you want to change the base?

feat(content-docs): new "created" metadata #7588

Conversation

dpang314 commented Jun 9, 2022 • edited Loading

Pre-flight checklist

Motivation

Test Plan

Test links

Related issues/PRs

netlify bot commented Jun 9, 2022 • edited Loading

✅ [V2]

github-actions bot commented Jun 9, 2022 • edited Loading

⚡️ Lighthouse report for the deploy preview of this PR

Josh-Cena left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber Jun 22, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dpang314 Jun 30, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

forresst left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber commented Aug 9, 2022

dpang314 commented Aug 16, 2022

slorber commented Aug 16, 2022

dpang314 commented Jun 9, 2022 •

edited

Loading

netlify bot commented Jun 9, 2022 •

edited

Loading

github-actions bot commented Jun 9, 2022 •

edited

Loading

slorber Jun 22, 2022 •

edited

Loading

dpang314 Jun 30, 2022 •

edited

Loading