refactor: simplify mapContributors configuration (#210)

* refactor: simplify mapContributors configuration

Signed-off-by: Neko Ayaka <neko@ayaka.moe>

* fix(git-changelog): mapAuthors.name also include in nameAlias, default return github link when no links but with username (#211)

* fix: support mapAuthor.name to nameAlias

> When searching for nameAlisa, consider mapAuthors.name as one of its name Alias at the same time, which will prevent the user from typing name and nameAlisa repeatedly in mapAuthor.

* fix: should return github link when without links and with username
* fix: modify mapContributors config accordingly

---------

Signed-off-by: Neko Ayaka <neko@ayaka.moe>
Co-authored-by: Northword <44738481+northword@users.noreply.github.com>

Author: nekomeowww

cspell.config.yaml

@@ -9,6 +9,7 @@ words:
   - Astro
   - Attributify
   - avatar
+  - ayaka
   - Baloo
   - baloo-2
   - blurhash
@@ -26,11 +27,13 @@ words:
   - evanw
   - execa
   - frontmatter
+  - Gitea
   - graymatter
   - iconify
   - Logseq
   - mkdist
   - napi
+  - neko
   - Nisekoi5
   - nodir
   - nolebase
@@ -41,6 +44,7 @@ words:
   - quotepath
   - Rehype
   - resvg
+  - rizumu
   - Roboto
   - shikijs
   - thumbhash

docs/.vitepress/theme/index.ts

@@ -1,4 +1,4 @@
-import { h } from 'vue'
+import { type Plugin, h } from 'vue'
 
 import { MotionPlugin } from '@vueuse/motion'
 import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
@@ -45,8 +45,9 @@ export default defineThemeUnconfig({
     app.component('IntegrationCard', IntegrationCard)
     app.component('HomeContent', HomeContent)
     app.component('ThumbhashPreview', ThumbhashPreview)
-    app.use(TwoslashFloatingVue)
-    app.use(MotionPlugin)
+
+    app.use(TwoslashFloatingVue as Plugin)
+    app.use(MotionPlugin as Plugin)
   },
   pluginPresets: [
     NolebasePluginPreset({
@@ -56,20 +57,23 @@ export default defineThemeUnconfig({
           mapContributors: [
             {
               name: 'Neko',
-              avatar: 'https://github.com/nekomeowww.png',
-              nameAliases: ['Neko Ayaka', 'Ayaka Neko'],
-              emailAliases: ['neko@ayaka.moe'],
+              username: 'nekomeowww',
+              mapByNameAliases: ['Neko Ayaka', 'Ayaka Neko'],
+              mapByEmailAliases: ['neko@ayaka.moe'],
             },
             {
               name: 'Rizumu',
-              avatar: 'https://github.com/LittleSound.png',
-              nameAliases: ['Rizumu Ayaka', 'Ayaka Rizumu'],
-              emailAliases: ['rizumu@ayaka.moe'],
+              username: 'LittleSound',
+              mapByNameAliases: ['Rizumu Ayaka', 'Ayaka Rizumu'],
+              mapByEmailAliases: ['rizumu@ayaka.moe'],
             },
             {
               name: 'Nisekoi5',
-              avatar: 'https://github.com/Nisekoi5.png',
-              nameAliases: ['Nisekoi5'],
+              username: 'Nisekoi5',
+            },
+            {
+              name: 'Northword',
+              username: 'northword',
             },
           ],
         },

docs/pages/en/integrations/vitepress-plugin-enhanced-mark/index.md

@@ -6,6 +6,14 @@ import packageJSON from '~/packages/vitepress-plugin-enhanced-mark/package.json'
 
 As an interesting little plugin, it adds a <mark>sliding animation</mark> to your `<mark>` highlighted elements.
 
+::: info 🤔 Performance drop? No!
+
+This plugin doesn't contain any JavaScript code, only one stylesheet is provided.
+
+Therefore, it should be theoretically performant, and won't cause any page lag.
+
+:::
+
 ## Features
 
 <div grid="~ cols-[auto_1fr] gap-1" items-start my-1>
@@ -21,14 +29,6 @@ As an interesting little plugin, it adds a <mark>sliding animation</mark> to you
   <span>Natively compatible with VitePress design</span>
 </div>
 
-::: info 🤔 Performance drop? No!
-
-This plugin doesn't contain any JavaScript code, only one stylesheet is provided.
-
-Therefore, it should be theoretically performant, and won't cause any page lag.
-
-:::
-
 ## Take a look
 
 It works like this:

docs/pages/en/integrations/vitepress-plugin-git-changelog/configure-ui.md

@@ -67,9 +67,9 @@ export const Theme: ThemeConfig = {
 }
 ```
 
-### Option `mapContributors` - Map contributors' information
+### Option `mapAuthors` - Map contributors' information
 
-The `mapContributors` field in the configuration options is used to map the contributors' information. You can provide the `mapContributors` field in the configuration options to map the contributors' information, including the display name, avatar, email, social links, and aliases.
+The `mapAuthors` field in the configuration options is used to map the contributors' information. You can provide the `mapAuthors` field in the configuration options to map the contributors' information, including the display name, avatar, email, social links, and aliases.
 
 Let's say we have these logs:
 
@@ -89,7 +89,7 @@ Author: John Doe <john.doe@anothersite.com>
 We now have two commits from the same person, with only the email address is different. By default, the plugin will treat them as two different contributors.
 Such case happens when you changed your name or email address in the past.
 
-To solve this, you can provide the `mapContributors` field in the configuration options to map the contributors' information:
+To solve this, you can provide the `mapAuthors` field in the configuration options to map the contributors' information:
 
 ```typescript twoslash
 import type { Theme as ThemeConfig } from 'vitepress'
@@ -106,11 +106,11 @@ export const Theme: ThemeConfig = {
     // Rest of the code...
 
     app.provide(InjectionKey, { // [!code focus]
-      mapContributors: [ // [!code focus]
+      mapAuthors: [ // [!code focus]
         { // [!code focus]
           name: 'John Doe', // [!code focus]
-          email: 'john.doe@example.com', // [!code focus]
-          emailAliases: ['john.doe@anothersite.com'] // [!code focus]
+          username: 'john_doe', // [!code focus]
+          mapByEmailAliases: ['john.doe@anothersite.com'] // [!code focus]
         } // [!code focus]
       ] // [!code focus]
     }) // [!code focus]
@@ -194,35 +194,35 @@ export interface Options {
    * ```
    */
   locales?: Record<string, Locale>
-  mapContributors?: Array<{
+  mapAuthors?: Array<{
     /**
      * The overriding display name of the contributor
      */
     name?: string
     /**
-     * The overriding avatar of the contributor
+     * The overriding GitHub, GitLab, Gitea username of the contributor
      */
-    avatar?: string
+    username?: string
     /**
-     * The overriding email of the contributor
+     * The overriding avatar of the contributor
      */
-    email?: string
+    avatar?: string
     /**
      * Whether to add a link to the contributor's profile
      */
-    links?: SocialEntry[]
+    links?: string | SocialEntry[]
     /**
      * More names to be recognized as the same contributor.
      *
      * Useful when you changed your name or email address in the past.
      */
-    nameAliases?: string[]
+    mapByNameAliases?: string[]
     /**
      * More emails to be recognized as the same contributor.
      *
      * Useful when you changed your email address in the past.
      */
-    emailAliases?: string[]
+    mapByEmailAliases?: string[]
   }>
 }
 ```

docs/pages/en/releases/migrations/v1-to-v2.md

@@ -204,6 +204,15 @@ import '@nolebase/vitepress-plugin-highlight-targeted-heading/client/style.css'
 
 ## Git-based page histories
 
+### UI config
+
+1. `mapContributors` now deprecated, please use `mapAuthors` instead since it's more neutral for writers.
+2. `nameAliases` now deprecated, please use `mapByNameAliases` instead, which is more clear and consistent with other plugins.
+3. `emailAliases` now deprecated, please use `mapByEmailAliases` instead, which is more clear and consistent with other plugins.
+4. Added new `username` field, which is the username of the author on GitHub used to fetch the avatar.
+
+### `Vite` config
+
 1. `includeDirs` and `includeExtensions` have been deprecated and merged into `include`, which is a list of glob modes with `!` negation.
 2. If a renderable page file located outside of the VitePress root (where `.vitepress` lives), please configure the `cwd` (current working directory) to the parent directory of the page files. (For example, in a Monorepo, if the source file that rendered a page s located outside of `docs/`, you need to set `cwd` to the root directory of the Monorepo instead of the root of VitePress.)
 3. No longer needed to configure `rewritePaths`, therefor `rewritePaths` is now deprecated, can be safely removed.

docs/pages/zh-CN/integrations/vitepress-plugin-enhanced-mark/index.md

@@ -6,6 +6,14 @@ import packageJSON from '~/packages/vitepress-plugin-enhanced-mark/package.json'
 
 这是一个很有意思的小插件，为你的 `<mark>` 高亮元素添加<mark>展开划过</mark>的小动画。
 
+::: info 🤔 性能问题？完全不用担心！
+
+该插件不包含任何 JavaScript 代码，只为 `<mark>` 元素提供动画样式。
+
+因此，理论上它的性能应该很好，不会造成任何页面掉帧卡顿。
+
+:::
+
 ## 功能
 
 <div grid="~ cols-[auto_1fr] gap-1" items-start my-1>
@@ -21,14 +29,6 @@ import packageJSON from '~/packages/vitepress-plugin-enhanced-mark/package.json'
   <span>原生与 VitePress 样式兼容</span>
 </div>
 
-::: info 🤔 Performance drop? No!
-
-This plugin doesn't contain any JavaScript code, only one stylesheet is provided.
-
-Therefore, it should be theoretically performant, and won't cause any page lag.
-
-:::
-
 ## 一览效果
 
 它看起来将会是这样的：

docs/pages/zh-CN/integrations/vitepress-plugin-git-changelog/configure-ui.md

@@ -87,7 +87,7 @@ Author: John Doe <john.doe@anothersite.com>
 现在我们有两个来自同一个人的提交，只有电子邮件地址不同。在不进行任何配置的默认情况下，插件会将它们视为两个不同的贡献者。
 这种情况通常是因为你或者其他贡献者更改了自己的电子邮件地址。
 
-要解决这个问题，我们可以使用 `mapContributors` 选项：
+要解决这个问题，我们可以使用 `mapAuthors` 选项：
 
 ```typescript twoslash
 import type { Theme as ThemeConfig } from 'vitepress'
@@ -104,11 +104,11 @@ export const Theme: ThemeConfig = {
     // Rest of the code...
 
     app.provide(InjectionKey, { // [!code focus]
-      mapContributors: [ // [!code focus]
+      mapAuthors: [ // [!code focus]
         { // [!code focus]
           name: 'John Doe', // [!code focus]
-          email: 'john.doe@example.com', // [!code focus]
-          emailAliases: ['john.doe@anothersite.com'] // [!code focus]
+          username: 'john_doe', // [!code focus]
+          mapByEmailAliases: ['john.doe@anothersite.com'] // [!code focus]
         } // [!code focus]
       ] // [!code focus]
     }) // [!code focus]
@@ -192,35 +192,35 @@ export interface Options {
    * ```
    */
   locales?: Record<string, Locale>
-  mapContributors?: Array<{
+  mapAuthors?: Array<{
     /**
      * The overriding display name of the contributor
      */
     name?: string
     /**
-     * The overriding avatar of the contributor
+     * The overriding GitHub, GitLab, Gitea username of the contributor
      */
-    avatar?: string
+    username?: string
     /**
-     * The overriding email of the contributor
+     * The overriding avatar of the contributor
      */
-    email?: string
+    avatar?: string
     /**
      * Whether to add a link to the contributor's profile
      */
-    links?: SocialEntry[]
+    links?: string | SocialEntry[]
     /**
      * More names to be recognized as the same contributor.
      *
      * Useful when you changed your name or email address in the past.
      */
-    nameAliases?: string[]
+    mapByNameAliases?: string[]
     /**
      * More emails to be recognized as the same contributor.
      *
      * Useful when you changed your email address in the past.
      */
-    emailAliases?: string[]
+    mapByEmailAliases?: string[]
   }>
 }
 ```

docs/pages/zh-CN/releases/migrations/v1-to-v2.md

@@ -204,6 +204,15 @@ import '@nolebase/vitepress-plugin-highlight-targeted-heading/client/style.css'
 
 ## 基于 Git 的页面历史
 
+### UI 配置
+
+1. `mapContributors` 现在已经被废弃，请使用对书写作者更为中立的 `mapAuthors`；
+2. `nameAliases` 现在已经被废弃，请使用更清晰，并与其他插件保持一致的 `mapByNameAliases`；
+3. `emailAliases` 现在已经被废弃，请使用更清晰，并与其他插件保持一致的 `mapByEmailAliases`；
+4. 添加了新的 `username` 字段映射，以便更好地支持 GitHub 头像。
+
+### `Vite` 配置
+
 1.`includeDirs` 和 `includeExtensions` 已被弃用并合并到 `include` 中，配置时，可以使用带有 `!` 作为否定的 glob 匹配模式。
 2.如果最终会被渲染的文件所对应的页面文件位于 VitePress 根目录（即 `.vitepress`所在目录）之外，**请将 `cwd`（当前工作目录）配置为页面文件的父目录**。(例如，在 Monorepo 中，如果需要读取 `docs/` 以外的文件，则需要将 `cwd` 设置为 Monorepo 的根目录，而不是 VitePress 的根目录）。
 3.不再需要配置 `rewritePaths`，因此 `rewritePaths` 已被弃用，可以安全删除。