Contributors
Overview
The theme supports adding contributor information to articles to better track your article contributors.
Article contributors are obtained through git commit history.
This feature is powered by @vuepress/plugin-git.
Note
This feature relies on the git log command to retrieve commit history for each markdown file, which can be relatively time-consuming, especially for large projects with extensive commit histories. Therefore, this feature is not enabled in development environments by default and is only enabled in production environments.
However, you can still enable it in development environments by setting theme.plugins.git to true for testing purposes.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
plugins: { git: true }
})
})Usage
The theme has built-in support for the @vuepress/plugin-git plugin, so you can use it without reinstalling.
Enable this feature in the theme configuration file:
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Enabled by default, only takes effect when plugins.git is true
// This configuration is invalid in plume.config.ts
contributors: true,
plugins: {
// If you declare it directly as true here, it means the feature is enabled in both development and production environments
git: process.env.NODE_ENV === 'production'
}
})
})Configuration
mode
Type:
'inline' | 'block'Default:
'inline'Description:
inline: Display contributor information at the bottom of the article page, alongside the last updated time. In this mode, only contributor names are displayed.
block: Insert contributor information at the end of the article content. This mode includes contributor names, links, and avatars. (As shown at the end of the current page's content)In
blockmode, avatars are displayed by default for all contributors, even if you haven't provided an avatar URL. The plugin will generate avatar URLs fromhttps://gravatar.com/based on email addresses or usernames.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
contributors: {
mode: 'block',
},
})
})info
Type:
ContributorInfo[]interface ContributorInfo { /** * Contributor's username on Git hosting service */ username: string /** * Name displayed for the contributor on the page, defaults to `username` */ name?: string /** * Contributor alias. Since the username saved in local git configuration might not match the hosting service username, * aliases can be used to map to the actual username */ alias?: string[] | string /** * Contributor avatar URL * If the git hosting service is `GitHub`, this can be omitted as the plugin will auto-fill it */ avatar?: string /** * Contributor profile URL * If the git hosting service is `GitHub`, this can be omitted as the plugin will auto-fill it */ url?: string }Description:
List of contributor information.
The username and email configured in the user's local git service might not match the user information on git hosting services (like GitHub, GitLab, Gitee). You can pre-configure contributor information here.
(For non-GitHub git hosting services such as GitLab and Gitee, since avatars and user URLs cannot be directly obtained from usernames, please supplement and complete user information here.)
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
contributors: {
mode: 'block',
info: [
{
username: 'pengzhanbo', // github username
alias: ['peng_zhan_bo'], // alias, username in local git configuration
}
]
},
})
})import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
contributors: {
mode: 'block',
info: [
{
username: 'pengzhanbo', // gitlab username
alias: ['peng_zhan_bo'], // alias, username in local git configuration
url: 'https://gitlab.com/pengzhanbo',
avatar: 'https://gitlab.com/uploads/-/system/user/avatar/1/avatar.png',
}
]
},
})
})import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
contributors: {
mode: 'block',
info: [
{
username: 'pengzhanbo', // gitee username
alias: ['peng_zhan_bo'], // alias, username in local git configuration
url: 'https://gitee.com/pengzhanbo',
avatar: 'https://foruda.gitee.com/avatar/1234455/avatar.png',
}
]
},
})
})import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
contributors: {
mode: 'block',
info: [
{
username: 'pengzhanbo', // bitbucket username
alias: ['peng_zhan_bo'], // alias, username in local git configuration
url: 'https://bitbucket.org/pengzhanbo',
avatar: 'https://bitbucket.org/pengzhanbo/avatar/1234455/avatar.png',
}
]
},
})
})import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
contributors: {
mode: 'block',
info: [
{
username: 'pengzhanbo', // username
alias: ['peng_zhan_bo'], // alias, username in local git configuration
url: 'https://your-git.com/pengzhanbo',
avatar: 'https://your-git.com/avatar.png',
}
]
},
})
})avatar
- Type:
boolean - Default:
true - Description: Whether to display contributor avatars
avatarPattern
Type:
stringDefault:
'https://github.com/:username.png'Description: Contributor avatar URL pattern
:usernamewill be replaced with the contributor's username
transform(contributors)
Type:
(contributors: GitContributor[]) => GitContributor[]interface GitContributor { name: string // Display name username: string // Git hosting service username email: string commits: number // Number of commits by the contributor avatar?: string }Description:
Contributor transformation function. This function should return a new list of contributors. You can add transformation logic here, such as sorting, deduplication, or completing information.
frontmatter
contributors
Type:
boolean | string[]Description:
Whether to display contributor information.
If your article comes from a third party and git commits cannot fully list all authors, you can supplement contributors here.
Notes
This feature requires your project to be under a Git repository so it can collect information from the commit history.
When building your site, you should ensure all commit records are accessible.
For example, CI workflows typically add the --depth 1 parameter when cloning your repository to avoid fetching all commit history. In this case, you need to fetch the full commit history instead (remove --depth 1) so the plugin can work properly in CI.
Services like GitHub Actions, Netlify, and Vercel do not fetch all commit history by default.
In GitHub Actions, you should configure fetch-depth: 0 for actions/checkout, i.e. fetch the full commit history.
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0For services like Netlify and Vercel, the processing method is relatively more complex. In such cases, you can first complete the build in GitHub Actions and output the build artifacts to a separate branch, then use that branch for deployment in Netlify or Vercel.
Info
For projects created via the theme's cli tool, when selecting the deployment method as GitHub Action, the build artifacts are output to the gh_pages branch. You can base your Netlify or Vercel deployment on this branch.
