chore: tweak

docs/plugins/development/git.md

@@ -89,6 +89,10 @@ This plugin will significantly slow down the speed of data preparation, especial
      * Contributor's username on the git hosting service
      */
     username: string
+    /**
+     * Contributor name displayed on the page, default is `username`
+     */
+    name?: string
     /**
      * The alias of the contributor,
      * Since contributors may have different usernames saved in their local git configuration
@@ -170,19 +174,13 @@ This plugin will significantly slow down the speed of data preparation, especial
 
   Whether to collect page changelogs or not.
 
-### enabled
+### filter
 
-- Type: `boolean | (page: Page) => boolean`
-
-- Default: `true`
+- Type: `(page: Page) => boolean`
 
 - Details:
 
-  Whether to enable this plugin or not.
-
-  - `true` - Enable the plugin
-  - `false` - Disable the plugin
-  - `(page: Page) => boolean` - if `true` is returned, git information will be collected for that page.
+  Page filter, if it returns `true`, the page will collect git information.
 
 ## Frontmatter
 

docs/zh/plugins/development/git.md

@@ -89,6 +89,10 @@ export default {
      * 贡献者在 git 托管服务中的用户名
      */
     username: string
+    /**
+     * 贡献者显示在页面上的名字， 默认为 `username`
+     */
+    name?: string
     /**
      * 贡献者别名， 由于贡献者可能在本地 git 配置中保存的 用户名与 git 托管服务用户名不一致，
      * 这时候可以通过别名映射到真实的用户名
@@ -164,19 +168,13 @@ export default {
 
   是否收集页面变更历史记录。
 
-### enabled
+### filter
 
-- 类型： `boolean | (page: Page) => boolean`
-
-- 默认值： `true`
+- 类型： `(page: Page) => boolean`
 
 - 详情：
 
-  是否启用该插件。
-
-  - `true` - 启用该插件
-  - `false` - 禁用该插件
-  - `(page: Page) => boolean` - 返回 `true` 时该页面会收集 git 信息
+  页面过滤器，如果返回 `true` ，该页面将收集 git 信息
 
 ## Frontmatter
 

plugins/development/plugin-git/src/node/gitPlugin.ts

@@ -20,7 +20,7 @@ export const gitPlugin =
     updatedTime,
     contributors,
     changelogs = false,
-    enabled = true,
+    filter,
     // eslint-disable-next-line @typescript-eslint/no-deprecated
     transformContributors,
   }: GitPluginOptions = {}): Plugin =>
@@ -37,15 +37,11 @@ export const gitPlugin =
       ) => {
         page.data.git = {}
 
-        if (
-          !isGitRepoValid ||
-          page.filePathRelative === null ||
-          enabled === false
-        ) {
+        if (!isGitRepoValid || page.filePathRelative === null) {
           return
         }
 
-        if (typeof enabled === 'function' && !enabled(page)) return
+        if (filter && !filter(page)) return
 
         const { frontmatter } = page
 

plugins/development/plugin-git/src/node/types.ts

@@ -2,11 +2,11 @@ import type { Page, PageFrontmatter } from 'vuepress'
 
 export interface GitPluginOptions {
   /**
-   * Whether to enable the plugin, If the value is `function`, it will be used to control which pages generate git information.
+   * Page filter, if it returns `true`, the page will collect git information.
    *
-   * 是否启用插件，如果值为`function`，将用于控制哪些页面生成git信息。
+   * 页面过滤器，如果返回 `true` ，该页面将收集 git 信息
    */
-  enabled?: boolean | ((page: Page) => boolean)
+  filter?: (page: Page) => boolean
   /**
    * Whether to get the created time of a page
    *
@@ -76,6 +76,14 @@ export interface ContributorConfig {
    * 贡献者在 git 托管服务中的用户名
    */
   username: string
+
+  /**
+   * Contributor name displayed on the page, default is `username`
+   *
+   * 贡献者显示在页面上的名字， 默认为 `username`
+   */
+  name?: string
+
   /**
    * The alias of the contributor,
    * Since contributors may have different usernames saved in their local git configuration
@@ -125,37 +133,36 @@ export interface ChangelogOptions {
 
   /**
    * Commit url pattern
-   * Default: ':repo/commit/:hash'
    *
    * - `:repo` - The url of the git repository
    * - `:hash` - Hash of the commit record
    *
    * 提交记录访问地址模式
-   * 默认值：':repo/commit/:hash'
    *
    * - `:repo` - git 仓库的访问地址
    * - `:hash` - 提交记录的 hash
+   *
+   * @default ':repo/commit/:hash'
    */
   commitUrlPattern?: string
 
   /**
    * Issue url pattern
-   * Default: ':repo/issues/:issue'
    *
    * - `:repo` - The url of the git repository
    * - `:issue` - Id of the issue
    *
    * issue 访问地址模式
-   * 默认值：':repo/issues/:issue'
    *
    * - `:repo` - git 仓库的访问地址
    * - `:issue` - issue 的 id
+   *
+   * @default ':repo/issues/:issue'
    */
   issueUrlPattern?: string
 
   /**
    * Tag url pattern
-   * Default: ':repo/releases/tag/:tag'
    *
    * - `:repo` - The url of the git repository
    * - `:tag` - Name of the tag
@@ -165,6 +172,8 @@ export interface ChangelogOptions {
    *
    * - `:repo` - git 仓库的访问地址
    * - `:tag` - tag 的名称
+   *
+   * @default ':repo/releases/tag/:tag'
    */
   tagUrlPattern?: string
 }
@@ -264,6 +273,10 @@ export interface GitChangelog
    * The url of the commit
    */
   commitUrl?: string
+  /**
+   * release tag
+   */
+  tag?: string
   /**
    * The url of the release tag
    */

plugins/development/plugin-git/src/node/utils/getCommits.ts

@@ -39,8 +39,8 @@ export const getRawCommits = async (
 export const parseRawCommits = (
   rawCommits: string[],
   filepath: string,
-): RawCommit[] => {
-  return rawCommits
+): RawCommit[] =>
+  rawCommits
     .filter((commit) => !!commit)
     .map((raw) => {
       const [hash, author, email, date, message, refs, body] = raw
@@ -57,7 +57,6 @@ export const parseRawCommits = (
         email,
       }
     })
-}
 
 export const mergeRawCommits = (commits: RawCommit[]): MergedRawCommit[] => {
   const commitMap = new Map<string, MergedRawCommit>()

plugins/development/plugin-git/src/node/utils/resolveChangelogs.ts

@@ -7,8 +7,8 @@ import type {
   MergedRawCommit,
 } from '../types.js'
 import {
-  getAuthorNameWithNoreplyEmail,
   getContributorWithConfig,
+  getUserNameWithNoreplyEmail,
 } from './resolveContributors.js'
 
 interface Pattern {
@@ -85,16 +85,15 @@ export const resolveChangelogs = (
   for (const commit of sliceCommits) {
     const { hash, message, date, author, email, refs } = commit
     const tag = parseTagName(refs)
-
+    const contributor = getContributorWithConfig(
+      contributors,
+      getUserNameWithNoreplyEmail(email) ?? author,
+    )
     const resolved: GitChangelog = {
       hash,
       date,
       email,
-      author:
-        getContributorWithConfig(
-          contributors,
-          getAuthorNameWithNoreplyEmail(email) ?? author,
-        )?.username ?? author,
+      author: contributor?.name ?? contributor?.username ?? author,
       message: app.markdown.renderInline(message),
     }
 
@@ -115,6 +114,8 @@ export const resolveChangelogs = (
         .replace(':hash', hash)
         .replace(':repo', repo)
 
+    if (tag) resolved.tag = tag
+
     if (pattern.tag && repo && tag)
       resolved.tagUrl = pattern.tag.replace(':tag', tag).replace(':repo', repo)
 

plugins/development/plugin-git/src/node/utils/resolveContributors.ts

@@ -7,7 +7,7 @@ import type {
   MergedRawCommit,
 } from '../types.js'
 
-export const getAuthorNameWithNoreplyEmail = (
+export const getUserNameWithNoreplyEmail = (
   email: string,
 ): string | undefined => {
   if (email.endsWith('@users.noreply.github.com')) {
@@ -38,35 +38,46 @@ export const getContributorWithConfig = (
   )
 }
 
-export const getRawContributors = (
+export const getRawContributors = async (
   commits: MergedRawCommit[],
   options: ContributorsOptions,
-): GitContributor[] => {
+  gitType: GitType | null = null,
+): Promise<GitContributor[]> => {
   const contributors = new Map<string, GitContributor>()
 
   for (const commit of commits) {
-    let { author } = commit
-    const { email } = commit
-
-    author = getAuthorNameWithNoreplyEmail(email) ?? author
-    const config = getContributorWithConfig(options.list ?? [], author)
-
-    if (config) author = config.username
-
-    const contributor = contributors.get(author + email)
+    const { author, email } = commit
+    const config = getContributorWithConfig(
+      options.list ?? [],
+      getUserNameWithNoreplyEmail(email) ?? author,
+    )
+    const username = config?.username ?? author
+    const name = config?.name ?? username
+
+    const contributor = contributors.get(name + email)
     if (contributor) {
       contributor.commits++
     } else {
       const item: GitContributor = {
-        name: author,
+        name,
         email,
         commits: 1,
       }
 
-      if (config?.avatar && options.avatar) item.avatar = config.avatar
-      if (config?.url) item.url = config.url
-
-      contributors.set(author + email, item)
+      if (options.avatar)
+        item.avatar =
+          config?.avatar ??
+          (gitType === 'github'
+            ? `https://avatars.githubusercontent.com/${username}?v=4`
+            : `https://gravatar.com/avatar/${await digestSHA256(email || username)}?d=retro`)
+
+      const url =
+        (config?.url ?? gitType === 'github')
+          ? `https://github.com/${username}`
+          : undefined
+      if (url) item.url = url
+
+      contributors.set(name + email, item)
     }
   }
 
@@ -93,37 +104,39 @@ export const resolveContributors = async (
   gitType: GitType | null = null,
   extraContributors?: string[],
 ): Promise<GitContributor[]> => {
-  let contributors = getRawContributors(commits, options)
+  let contributors = await getRawContributors(commits, options, gitType)
 
   if (options.list?.length && extraContributors?.length) {
     for (const extraContributor of extraContributors) {
-      const config = getContributorWithConfig(options.list, extraContributor)
-      if (
-        config &&
-        !contributors.some((item) => item.name === extraContributor)
-      ) {
-        contributors.push({
-          name: config.username,
+      if (!contributors.some((item) => item.name === extraContributor)) {
+        const config = getContributorWithConfig(options.list, extraContributor)
+        if (!config) continue
+
+        const item: GitContributor = {
+          name: config.name ?? extraContributor,
           email: '',
           commits: 0,
-          url: config.url,
-          avatar: config.avatar,
-        })
+        }
+
+        if (options.avatar)
+          item.avatar =
+            config.avatar ??
+            (gitType === 'github'
+              ? `https://avatars.githubusercontent.com/${config.username}?v=4`
+              : `https://gravatar.com/avatar/${await digestSHA256(config.username)}?d=retro`)
+
+        const url =
+          (config.url ?? gitType === 'github')
+            ? `https://github.com/${config.username}`
+            : undefined
+        if (url) item.url = url
+
+        contributors.push(item)
       }
     }
   }
 
   if (options.transform) contributors = await options.transform(contributors)
 
-  for (const contributor of contributors) {
-    if (gitType === 'github') {
-      contributor.url ??= `https://github.com/${contributor.name}`
-      if (options.avatar)
-        contributor.avatar ??= `https://avatars.githubusercontent.com/${contributor.name}?v=4`
-    } else if (options.avatar) {
-      contributor.avatar ??= `https://gravatar.com/avatar/${await digestSHA256(contributor.email || contributor.name)}?d=retro`
-    }
-  }
-
   return contributors
 }