feat(plugin-git): improve composables and add docs

docs/plugins/development/git.md

@@ -269,6 +269,131 @@ gitInclude:
 
   Whether to collect the change history for the current page, this value will override the [changelog](#changelog) configuration item.
 
+## Composables
+
+You can import the following composables from `@vuepress/plugin-git/client`.
+
+### useChangelog
+
+Get the changelog of the current page.
+
+```ts
+export interface GitChangelogItem {
+  /**
+   * Commit hash
+   */
+  hash: string
+  /**
+   * Unix timestamp in milliseconds
+   */
+  time: number
+  /**
+   * Commit message
+   */
+  message: string
+  /**
+   * The url of the commit
+   */
+  commitUrl?: string
+  /**
+   * release tag
+   */
+  tag?: string
+  /**
+   * The url of the release tag
+   */
+  tagUrl?: string
+  /**
+   * Commit author name
+   */
+  author: string
+  /**
+   * Commit author email
+   */
+  email: string
+
+  /**
+   * The co-authors of the commit
+   */
+  coAuthors?: CoAuthorInfo[]
+  /**
+   * Date text of the commit
+   */
+  date: string
+}
+
+export const useChangelog: (
+  enabled?: MaybeRefOrGetter<boolean>,
+) => ComputedRef<GitChangelogItem[]>
+```
+
+### useContributors
+
+Get the contributors of the current page.
+
+```ts
+export interface GitContributorInfo {
+  /**
+   * Contributor display name
+   */
+  name: string
+  /**
+   * Contributor email
+   */
+  email: string
+
+  /**
+   * Contributor username on the git hosting service
+   */
+  username: string
+  /**
+   * Number of commits
+   */
+  commits: number
+  /**
+   * Contributor avatar
+   */
+  avatar?: string
+  /**
+   * The url of the contributor
+   */
+  url?: string
+}
+
+export const useContributors: (
+  enabled?: MaybeRefOrGetter<boolean>,
+) => ComputedRef<GitContributorInfo[]>
+```
+
+### useLastUpdated
+
+Get the last updated time of the current page.
+
+```ts
+export interface LastUpdated {
+  /**
+   * The date object of the last updated time
+   */
+  date: Date
+  /**
+   * The ISO string of the last updated time
+   */
+  iso: string
+  /**
+   * The formatted text of the last updated time
+   */
+  text: string
+  /**
+   * The locale of the last updated time
+   */
+  locale: string
+}
+
+export const useLastUpdated: (
+  enabled?: MaybeRefOrGetter<boolean>,
+) => ComputedRef<LastUpdated | null>
+```
+
 ## Page Data
 
 This plugin will add a `git` field to page data.

docs/zh/plugins/development/git.md

@@ -258,6 +258,131 @@ gitInclude:
 
   当前页面是否获取变更历史记录，该值会覆盖 [changelog](#changelog) 配置项。
 
+## 可组合式 API
+
+你可以从 `@vuepress/plugin-git/client` 中导入以下可组合式 API。
+
+### useChangelog
+
+获取当前页面的变更历史记录。
+
+```ts
+export interface GitChangelogItem {
+  /**
+   * Commit hash
+   */
+  hash: string
+  /**
+   * Unix timestamp in milliseconds
+   */
+  time: number
+  /**
+   * Commit message
+   */
+  message: string
+  /**
+   * The url of the commit
+   */
+  commitUrl?: string
+  /**
+   * release tag
+   */
+  tag?: string
+  /**
+   * The url of the release tag
+   */
+  tagUrl?: string
+  /**
+   * Commit author name
+   */
+  author: string
+  /**
+   * Commit author email
+   */
+  email: string
+
+  /**
+   * The co-authors of the commit
+   */
+  coAuthors?: CoAuthorInfo[]
+  /**
+   * Date text of the commit
+   */
+  date: string
+}
+
+export const useChangelog: (
+  enabled?: MaybeRefOrGetter<boolean>,
+) => ComputedRef<GitChangelogItem[]>
+```
+
+### useContributors
+
+获取当前页面的贡献者信息。
+
+```ts
+export interface GitContributorInfo {
+  /**
+   * Contributor display name
+   */
+  name: string
+  /**
+   * Contributor email
+   */
+  email: string
+
+  /**
+   * Contributor username on the git hosting service
+   */
+  username: string
+  /**
+   * Number of commits
+   */
+  commits: number
+  /**
+   * Contributor avatar
+   */
+  avatar?: string
+  /**
+   * The url of the contributor
+   */
+  url?: string
+}
+
+export const useContributors: (
+  enabled?: MaybeRefOrGetter<boolean>,
+) => ComputedRef<GitContributorInfo[]>
+```
+
+### useLastUpdated
+
+获取当前页面的最后更新时间。
+
+```ts
+export interface LastUpdated {
+  /**
+   * The date object of the last updated time
+   */
+  date: Date
+  /**
+   * The ISO string of the last updated time
+   */
+  iso: string
+  /**
+   * The formatted text of the last updated time
+   */
+  text: string
+  /**
+   * The locale of the last updated time
+   */
+  locale: string
+}
+
+export const useLastUpdated: (
+  enabled?: MaybeRefOrGetter<boolean>,
+) => ComputedRef<LastUpdated | null>
+```
+
 ## 页面数据
 
 该插件会向页面数据中添加一个 `git` 字段。

e2e/tests/plugin-theme-data/theme-data.spec.ts

@@ -71,7 +71,6 @@ test.describe('plugin-theme-data', () => {
       editLink: true,
       editLinkText: 'Edit this page',
       lastUpdated: true,
-      lastUpdatedText: 'Last Updated',
       contributors: true,
       contributorsText: 'Contributors',
       notFound: [

plugins/development/plugin-git/src/client/components/GitChangelog.ts

@@ -29,7 +29,7 @@ export const GitChangelog = defineComponent({
   setup(props) {
     const changelog = useChangelog()
     const locale = useGitLocaleConfig()
-    const latestUpdated = useLastUpdated()
+    const lastUpdated = useLastUpdated()
 
     const [active, toggleActive] = useToggle()
 
@@ -40,7 +40,7 @@ export const GitChangelog = defineComponent({
         [
           h('div', { class: 'vp-latest-updated' }, [
             h('span', { class: 'vp-changelog-icon' }),
-            h('span', { 'data-allow-mismatch': '' }, latestUpdated.value!.text),
+            h('span', { 'data-allow-mismatch': '' }, lastUpdated.value!.text),
           ]),
           h('div', [
             h('span', { class: 'vp-changelog-menu-icon' }),

plugins/development/plugin-git/src/client/composables/useChangelog.ts

@@ -1,5 +1,5 @@
-import type { ComputedRef } from 'vue'
-import { computed } from 'vue'
+import type { ComputedRef, MaybeRefOrGetter } from 'vue'
+import { computed, toValue } from 'vue'
 import { usePageData, usePageFrontmatter, usePageLang } from 'vuepress/client'
 import type {
   GitChangelogInfo,
@@ -19,7 +19,9 @@ const RE_ISSUE = /#(\d+)/g
 
 export const useChangelog =
   typeof __GIT_CHANGELOG__ === 'boolean' && __GIT_CHANGELOG__
-    ? (): ComputedRef<GitChangelogItem[]> => {
+    ? (
+        enabled: MaybeRefOrGetter<boolean> = true,
+      ): ComputedRef<GitChangelogItem[]> => {
         const frontmatter = usePageFrontmatter<GitPluginFrontmatter>()
         const lang = usePageLang()
         const page = usePageData<GitPluginPageData>()
@@ -28,7 +30,8 @@ export const useChangelog =
         const repo = resolveRepoLink(gitOptions.repo, provider)
 
         return computed(() => {
-          if (frontmatter.value.changelog === false) return []
+          if (frontmatter.value.changelog === false || !toValue(enabled))
+            return []
 
           const formatter = new Intl.DateTimeFormat(lang.value, {
             dateStyle: 'short',

plugins/development/plugin-git/src/client/composables/useContributors.ts

@@ -1,5 +1,5 @@
-import type { ComputedRef } from 'vue'
-import { computed } from 'vue'
+import type { ComputedRef, MaybeRefOrGetter } from 'vue'
+import { computed, toValue } from 'vue'
 import { usePageData, usePageFrontmatter } from 'vuepress/client'
 import type {
   GitContributorInfo,
@@ -11,12 +11,15 @@ declare const __GIT_CONTRIBUTORS__: boolean
 
 export const useContributors =
   typeof __GIT_CONTRIBUTORS__ === 'boolean' && __GIT_CONTRIBUTORS__
-    ? (): ComputedRef<GitContributorInfo[]> => {
+    ? (
+        enabled: MaybeRefOrGetter<boolean> = true,
+      ): ComputedRef<GitContributorInfo[]> => {
         const frontmatter = usePageFrontmatter<GitPluginFrontmatter>()
         const page = usePageData<GitPluginPageData>()
 
         return computed(() => {
-          if (frontmatter.value.contributors === false) return []
+          if (frontmatter.value.contributors === false || !toValue(enabled))
+            return []
 
           // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
           return page.value.git?.contributors ?? []

plugins/development/plugin-git/src/client/composables/useGitLocales.ts

@@ -5,7 +5,8 @@ import type { GitLocaleData } from '../../shared/index.js'
 
 declare const __GIT_LOCALES__: ExactLocaleConfig<GitLocaleData>
 
-export const locales = __GIT_LOCALES__
+export const locales =
+  typeof __GIT_LOCALES__ === 'undefined' ? {} : __GIT_LOCALES__
 
 export const useGitLocaleConfig = (): ComputedRef<GitLocaleData> =>
   useLocaleConfig(locales)