From 2055bc58642564e771c80f6c21203262fbd89422 Mon Sep 17 00:00:00 2001 From: WizardsBowl Date: Wed, 25 Feb 2026 18:18:58 +0800 Subject: [PATCH] feat(theme): add created timestamp --- docs/.vitepress/config.ts | 1 + docs/config.ts | 1 + docs/en/reference/default-theme-config.md | 40 ++++++++++++++ docs/en/reference/default-theme-created.md | 29 ++++++++++ docs/en/reference/frontmatter-config.md | 13 +++++ docs/en/reference/runtime-api.md | 1 + docs/en/reference/site-config.md | 9 ++++ docs/zh/config.ts | 5 ++ docs/zh/reference/default-theme-config.md | 40 ++++++++++++++ docs/zh/reference/default-theme-created.md | 29 ++++++++++ docs/zh/reference/frontmatter-config.md | 13 +++++ docs/zh/reference/runtime-api.md | 1 + docs/zh/reference/site-config.md | 9 ++++ .../theme-default/components/VPDocFooter.vue | 19 +++++-- ...stUpdated.vue => VPDocFooterTimestamp.vue} | 39 ++++++++++---- src/node/build/generateSitemap.ts | 4 +- src/node/config.ts | 1 + src/node/markdownToVue.ts | 16 +++++- src/node/plugin.ts | 6 ++- src/node/siteConfig.ts | 2 + src/node/utils/getGitTimestamp.ts | 54 ++++++++++++++++--- src/shared/shared.ts | 1 + types/default-theme.d.ts | 22 ++++++++ types/shared.d.ts | 1 + 24 files changed, 329 insertions(+), 27 deletions(-) create mode 100644 docs/en/reference/default-theme-created.md create mode 100644 docs/zh/reference/default-theme-created.md rename src/client/theme-default/components/{VPDocFooterLastUpdated.vue => VPDocFooterTimestamp.vue} (57%) diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 4c65ec7e..04d7d99c 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -20,6 +20,7 @@ export default defineConfig({ }, lastUpdated: true, + created: true, cleanUrls: true, metaChunk: true, diff --git a/docs/config.ts b/docs/config.ts index 8620d955..7ad4d72b 100644 --- a/docs/config.ts +++ b/docs/config.ts @@ -132,6 +132,7 @@ function sidebarReference(): DefaultTheme.SidebarItem[] { { text: 'Prev / Next Links', link: 'prev-next-links' }, { text: 'Edit Link', link: 'edit-link' }, { text: 'Last Updated Timestamp', link: 'last-updated' }, + { text: 'Created Timestamp', link: 'created' }, { text: 'Search', link: 'search' }, { text: 'Carbon Ads', link: 'carbon-ads' } ] diff --git a/docs/en/reference/default-theme-config.md b/docs/en/reference/default-theme-config.md index 4868cda3..a6293bf2 100644 --- a/docs/en/reference/default-theme-config.md +++ b/docs/en/reference/default-theme-config.md @@ -338,6 +338,46 @@ export interface LastUpdatedOptions { } ``` +## created + +- Type: `CreatedOptions` + +Allows customization for the created text and date format. + +```ts +export default { + themeConfig: { + created: { + text: 'Created at', + formatOptions: { + dateStyle: 'full', + timeStyle: 'medium' + } + } + } +} +``` + +```ts +export interface CreatedOptions { + /** + * Set custom created text. + * + * @default 'Created' + */ + text?: string + + /** + * Set options for created time formatting. + * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options + * + * @default + * { dateStyle: 'short', timeStyle: 'short' } + */ + formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean } + } +``` + ## algolia - Type: `AlgoliaSearch` diff --git a/docs/en/reference/default-theme-created.md b/docs/en/reference/default-theme-created.md new file mode 100644 index 00000000..ae8a38c7 --- /dev/null +++ b/docs/en/reference/default-theme-created.md @@ -0,0 +1,29 @@ +# Created + +The created time of the content will be displayed in the lower right corner of the page. To enable it, add `created` options to your config. + +::: info +VitePress displays the "created" time using the timestamp of the first Git commit for each file. To enable this, the Markdown file must be committed to Git. + +Internally, VitePress runs `git log -1 --pretty=%at --follow --diff-filter=A` on each file to retrieve its timestamp. If all pages show the same created time, please refer to the same paragraph on the [Last Updated](./default-theme-last-updated) page. +::: + +## Site-Level Config + +```js +export default { + created: true +} +``` + +## Frontmatter Config + +This can be disabled per-page using the `created` option on frontmatter: + +```yaml +--- +created: false +--- +``` + +Also refer [Default Theme: Created](./default-theme-config#created) for more details. Any truthy value at theme-level will also enable the feature unless explicitly disabled at site or page level. diff --git a/docs/en/reference/frontmatter-config.md b/docs/en/reference/frontmatter-config.md index 4d6f86c0..711fe5f7 100644 --- a/docs/en/reference/frontmatter-config.md +++ b/docs/en/reference/frontmatter-config.md @@ -180,6 +180,19 @@ lastUpdated: false --- ``` +### created + +- Type: `boolean | Date` +- Default: `true` + +Whether to display [created](./default-theme-created) text in the footer of the current page. If a datetime is specified, it will be displayed instead of the first git commit timestamp. + +```yaml +--- +created: false +--- +``` + ### editLink - Type: `boolean` diff --git a/docs/en/reference/runtime-api.md b/docs/en/reference/runtime-api.md index ca1f3987..894d53a1 100644 --- a/docs/en/reference/runtime-api.md +++ b/docs/en/reference/runtime-api.md @@ -55,6 +55,7 @@ interface PageData { params?: Record isNotFound?: boolean lastUpdated?: number + created?: number } ``` diff --git a/docs/en/reference/site-config.md b/docs/en/reference/site-config.md index 70df8a31..03c69dd3 100644 --- a/docs/en/reference/site-config.md +++ b/docs/en/reference/site-config.md @@ -513,6 +513,15 @@ Whether to get the last updated timestamp for each page using Git. The timestamp When using the default theme, enabling this option will display each page's last updated time. You can customize the text via [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) option. +### created + +- Type: `boolean` +- Default: `false` + +Whether to get the created timestamp for each page using Git. The timestamp will be included in each page's page data, accessible via [`useData`](./runtime-api#usedata). + +When using the default theme, enabling this option will display each page's created time. You can customize the text via [`themeConfig.created.text`](./default-theme-config#created) option. + ## Customization ### markdown diff --git a/docs/zh/config.ts b/docs/zh/config.ts index 91687c54..6920d3f1 100644 --- a/docs/zh/config.ts +++ b/docs/zh/config.ts @@ -40,6 +40,10 @@ export default defineAdditionalConfig({ text: '最后更新于' }, + created: { + text: '创建于' + }, + notFound: { title: '页面未找到', quote: @@ -160,6 +164,7 @@ function sidebarReference(): DefaultTheme.SidebarItem[] { { text: '上下页链接', link: 'prev-next-links' }, { text: '编辑链接', link: 'edit-link' }, { text: '最后更新时间戳', link: 'last-updated' }, + { text: '创建时间戳', link: 'created' }, { text: '搜索', link: 'search' }, { text: 'Carbon Ads', link: 'carbon-ads' } ] diff --git a/docs/zh/reference/default-theme-config.md b/docs/zh/reference/default-theme-config.md index c4f76ea5..0caf0528 100644 --- a/docs/zh/reference/default-theme-config.md +++ b/docs/zh/reference/default-theme-config.md @@ -324,6 +324,46 @@ export interface LastUpdatedOptions { } ``` +## created + +- 类型：`CreatedOptions` + +允许自定义文档创建的文本和日期格式。 + +```ts +export default { + themeConfig: { + created: { + text: 'Created at', + formatOptions: { + dateStyle: 'full', + timeStyle: 'medium' + } + } + } +} +``` + +```ts +export interface CreatedOptions { + /** + * Set custom created text. + * + * @default 'Created' + */ + text?: string + + /** + * Set options for created time formatting. + * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat#using_options + * + * @default + * { dateStyle: 'short', timeStyle: 'short' } + */ + formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean } + } +``` + ## algolia - 类型：`AlgoliaSearch` diff --git a/docs/zh/reference/default-theme-created.md b/docs/zh/reference/default-theme-created.md new file mode 100644 index 00000000..492f0de8 --- /dev/null +++ b/docs/zh/reference/default-theme-created.md @@ -0,0 +1,29 @@ +# 创建于 {#created} + +文档的创建时间会显示在页面右下角。要启用它，请将 `created` 选项添加到配置中。 + +::: tip +VitePress 通过每个文件第一次 Git 提交的时间戳显示"创建"时间，因此你必须提交 markdown 文件才能看到创建时间。 + +具体实现上，VitePress 会对每个文件执行`git log -1 --pretty=%at --follow --diff-filter=A`命令以获取时间戳。若所有页面显示相同的创建时间，请参考[最后更新时间](./default-theme-last-updated)页面中的相同段落。 +::: + +## 全局配置 {#site-level-config} + +```js +export default { + created: true +} +``` + +## frontmatter 配置 {#frontmatter-config} + +可以使用 frontmatter 上的 `created` 选项单独禁用某个页面的最后更新展示： + +```yaml +--- +created: false +--- +``` + +另请参阅[默认主题：创建时间](./default-theme-config#created) 了解更多详细信息。主题级别的任何 [truthy](https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy) 值也将启用该功能，除非在站点或页面级别明确禁用。 diff --git a/docs/zh/reference/frontmatter-config.md b/docs/zh/reference/frontmatter-config.md index 4ee5d961..80ede6f3 100644 --- a/docs/zh/reference/frontmatter-config.md +++ b/docs/zh/reference/frontmatter-config.md @@ -174,6 +174,19 @@ lastUpdated: false --- ``` +### created + +- 类型：`boolean | Date` +- 默认值：`true` + +是否在当前页面的页脚中显示[创建时间](./default-theme-created)的文本。如果指定了日期时间，则会显示该日期时间而不是初次 git 提交的时间戳。 + +```yaml +--- +created: false +--- +``` + ### editLink - 类型：`boolean` diff --git a/docs/zh/reference/runtime-api.md b/docs/zh/reference/runtime-api.md index 35a57872..1767c351 100644 --- a/docs/zh/reference/runtime-api.md +++ b/docs/zh/reference/runtime-api.md @@ -51,6 +51,7 @@ interface PageData { params?: Record isNotFound?: boolean lastUpdated?: number + created?: number } ``` diff --git a/docs/zh/reference/site-config.md b/docs/zh/reference/site-config.md index f81239c5..c45c88eb 100644 --- a/docs/zh/reference/site-config.md +++ b/docs/zh/reference/site-config.md @@ -511,6 +511,15 @@ export default { 使用默认主题时，启用此选项将显示每个页面的最后更新时间。可以通过 [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext) 选项自定义文本。 +### created + +- 类型：`boolean` +- 默认值： `false` + +是否使用 Git 获取每个页面的文档创建时间戳。时间戳将包含在每个页面的页面数据中，可通过 [`useData`](./runtime-api#usedata) 访问。 + +使用默认主题时，启用此选项将显示每个页面的文档创建时间。可以通过 [`themeConfig.created.text`](./default-theme-config#created) 选项自定义文本。 + ## 自定义 {#customization} ### markdown diff --git a/src/client/theme-default/components/VPDocFooter.vue b/src/client/theme-default/components/VPDocFooter.vue index 0b6ff2a8..cd72e831 100644 --- a/src/client/theme-default/components/VPDocFooter.vue +++ b/src/client/theme-default/components/VPDocFooter.vue @@ -4,7 +4,7 @@ import { useData } from '../composables/data' import { useEditLink } from '../composables/edit-link' import { usePrevNext } from '../composables/prev-next' import VPLink from './VPLink.vue' -import VPDocFooterLastUpdated from './VPDocFooterLastUpdated.vue' +import VPDocFooterTimestamp from './VPDocFooterTimestamp.vue' const { theme, page, frontmatter } = useData() @@ -15,10 +15,12 @@ const hasEditLink = computed( () => theme.value.editLink && frontmatter.value.editLink !== false ) const hasLastUpdated = computed(() => page.value.lastUpdated) +const hasCreated = computed(() => page.value.created) const showFooter = computed( () => hasEditLink.value || hasLastUpdated.value || + hasCreated.value || control.value.prev || control.value.next ) @@ -28,7 +30,7 @@ const showFooter = computed(