Configuration
The Git-based page histories plugin currently provides configuration options related to Internationalization and Contributors section.
Configure in VitePress
There are two ways to configure.
Supply options when installing the Vue plugin
If you've never seen a colored diff before
This is a markup rule for displaying diff in the user interface (UI).
Red parts usually represents the lines you are going to remove, commonly appeared with a Minus sign -, or you could simply understand it as: this line will be removed.
Green parts usually represents the lines you are going to add, commonly appeared with a Plus sign +, or you could simply understand it as: this line will be added.
To learn more about diff, you can check out this answer about the history of diffutils and Git's documentation
import type { as ThemeConfig } from 'vitepress'
import from 'vitepress/theme'
import { } from '@nolebase/vitepress-plugin-git-changelog/client'
export const : ThemeConfig = {
: ,
: () => {
// Rest of the code...
},
({ }) {
// Rest of the code...
.(, {
// Configuration...
})
// Rest of the code...
},
}Supply options with Vue's dependency injection
Since VitePress doesn't provide more functionality for the default theme to extend the default theme configuration, it is not friendly to the type checking and maintenance of the configuration if we directly modify the major VitePress configuration object to provide options for the plugin.
Therefore we offer a way with Vue's dependency injection to provide options and configuration for the plugin:
If you've never seen a colored diff before
This is a markup rule for displaying diff in the user interface (UI).
Red parts usually represents the lines you are going to remove, commonly appeared with a Minus sign -, or you could simply understand it as: this line will be removed.
Green parts usually represents the lines you are going to add, commonly appeared with a Plus sign +, or you could simply understand it as: this line will be added.
To learn more about diff, you can check out this answer about the history of diffutils and Git's documentation
import type { as ThemeConfig } from 'vitepress'
import from 'vitepress/theme'
import { } from '@nolebase/vitepress-plugin-git-changelog/client'
export const : ThemeConfig = {
: ,
: () => {
// Rest of the code...
},
({ }) {
// Rest of the code...
.(, {
// Configuration...
})
// Rest of the code...
},
}Option mapAuthors - Map contributors' information
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:
commit 1
Author: John Doe <[email protected]>
Date: Fri Oct 1 12:00:00 2021 +0800
Add a new feature
commit 2
Author: John Doe <[email protected]>
Fix a bugWe 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 mapAuthors field in the configuration options to map the contributors' information:
import type { as ThemeConfig } from 'vitepress'
import from 'vitepress/theme'
import { } from '@nolebase/vitepress-plugin-git-changelog/client'
export const : ThemeConfig = {
: ,
: () => {
// Rest of the code...
},
({ }) {
// Rest of the code...
.(, {
: [
{
: 'John Doe',
: 'john_doe',
: ['[email protected]']
}
]
})
// Rest of the code...
},
}Options inside
Deprecating warning
We have changed the structure of locales config since 2.0.0-rc14, and the old structure will be deprecated in the next major version. Please update your configuration according to the new structure. For migration guides, see Migrate from v1 to v2.
Complete configurable options
/**
* Options
*/
export interface Options {
/**
* Internationalization configuration
*
* When configuring, please configure according to the language code configured in
* VitePress internationalization configuration. In the following configuration, 'en'
* and 'zh-CN' are the language codes configured in VitePress internationalization
* configuration.
*
* @default undefined
* @example
* ```ts
* {
* locales: {
* 'en': {
* changelog: {
* title: 'Changelog',
* noData: 'No recent changes',
* lastEdited: 'This page was last edited {{daysAgo}}',
* lastEditedDateFnsLocaleName: 'enUS',
* viewFullHistory: 'View full history',
* committedOn: ' on {{date}}',
* }
* },
* 'zh-CN': {
* changelog: {
* title: '页面历史'
* noData: '暂无最近变更历史',
* lastEdited: '本页面最后编辑于 {{daysAgo}}',
* lastEditedDateFnsLocaleName: 'zhCN',
* viewFullHistory: '查看完整历史',
* committedOn: '于 {{date}} 提交',
* }
* },
* }
* }
* ```
*/
?: <string, Locale>
?: <{
/**
* The overriding display name of the contributor
*/
?: string
/**
* The overriding GitHub, GitLab, Gitea username of the contributor
*/
?: string
/**
* The overriding avatar of the contributor
*/
?: string
/**
* Whether to add a link to the contributor's profile
*/
?: string | SocialEntry[]
/**
* More names to be recognized as the same contributor.
*
* Useful when you changed your name or email address in the past.
*/
?: string[]
/**
* More emails to be recognized as the same contributor.
*
* Useful when you changed your email address in the past.
*/
?: string[]
}>
}For more information on internationalization configuration, see Internationalization.
Internationalization
Caution
The Git-based page histories plugin does not use vue-i18n as an i18n toolkit since most of VitePress probably uses VitePress's internationalization features for internationalization, so it is impossible to override the fields of the localized text of the Git-based page histories plugin with vue-i18n, but you can achieve it with the locales field in Configuration.
The same as other VitePress plugins, Git-based page histories plugin supports internationalization by default, with English and Simplified Chinese as supported languages.
You can override the plugin's localized text through configuration, and before you start, you need to understand how VitePress is internationalized: Internationalization of VitePress. The Git-based page histories plugin reads the VitePress language field by default, so you'll need to be careful to keep the internationalized language code the same as the VitePress language code when configuring it.
Configure in VitePress
In the Configuration section, we've learned how to provide configuration options for the Git-based page histories plugin in VitePress, and we can configure internationalization by adding the locales field to the configuration options:
If you've never seen a colored diff before
This is a markup rule for displaying diff in the user interface (UI).
Red parts usually represents the lines you are going to remove, commonly appeared with a Minus sign -, or you could simply understand it as: this line will be removed.
Green parts usually represents the lines you are going to add, commonly appeared with a Plus sign +, or you could simply understand it as: this line will be added.
To learn more about diff, you can check out this answer about the history of diffutils and Git's documentation
import type { as ThemeConfig } from 'vitepress'
import from 'vitepress/theme'
import { } from '@nolebase/vitepress-plugin-inline-link-preview/client'
// Rest of code...
export const : ThemeConfig = {
: ,
: () => {
// Rest of code...
},
({ }) {
// Rest of code...
.(, {
: { // i18n
'zh-CN': { // configure for Simplified Chinese
: {
: '加载中...',
: '加载中',
}
},
'en': { // configure for English
: {
: 'Loading...',
: 'Loading',
}
}
}
})
// Rest of code...
},
}Locales options
Deprecating warning
We have changed the structure of locales config since 2.0.0-rc14, and the old structure will be deprecated in the next major version. Please update your configuration according to the new structure. For migration guides, see Migrate from v1 to v2.
Complete internationalization field options
/**
* Locale
*/
interface Locale {
/**
* The changelog section configuration
*/
?: {
/**
* The title of the changelog section
*/
?: string
/**
* What to display when there are no logs
*/
?: string
/**
* What to display when the page was last edited
*/
?: string
/**
* The name of the locale to use for date-fns
*/
?: string
/**
* What to display when the user wants to view the full history
*/
?: string
/**
* What to display when the commit was committed
*/
?: string
}
/**
* The contributors section configuration
*/
?: {
/**
* The title of the contributors section
*/
?: string
/**
* What to display when there are no contributors
*/
?: string
}
}Accessibility
The Git-based page histories plugin provides accessibility support by default. You can override accessible labels (aria-label) via Configuration in the same way as Internationalization, see Locales Options for a description of what labels can be configured for accessibility.
More customizations?
It is possible though.
Caution
Configure on your own is for those who know and understand what they are doing. If you don't know what you are doing or encounter problems during configuration, please read and follow the Integrate with VitePress section.
The Git-based page histories plugin exports the components it uses internally, so if you don't like the style and encapsulation of the default components, you can always create your own components and use them instead.
Before you start
By default, the GitChangelog plugin for Vite will automatically configure the optimizeDeps and ssr options for you. However, if you just want the UI widget without the data fetching plugin, you must configure the optimizeDeps and ssr options manually like this:
import { } from 'vite'
export default (() => {
return {
: {
: [
// @rive-app/canvas is a CJS/UMD module, so it needs to be included here
// for Vite to properly bundle it.
'@nolebase/vitepress-plugin-git-changelog > @nolebase/ui > @rive-app/canvas',
],
: [
'@nolebase/vitepress-plugin-git-changelog/client',
],
},
: {
: [
'@nolebase/vitepress-plugin-git-changelog',
// @nolebase/ui required here as noExternal to avoid the following error:
// TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".vue" for ...
// Read more here: https://github.com/vuejs/vitepress/issues/2915
// And here: https://stackblitz.com/edit/vite-gjz9zf?file=docs%2F.vitepress%2Fconfig.ts
'@nolebase/ui',
],
},
// other vite configurations...
}
})Install as a Vue plugin
import {
} from '@nolebase/vitepress-plugin-git-changelog/client'If you are working on a VitePress and wanted to install it into Vue instance, you can do it like this:
import type { as ThemeConfig } from 'vitepress'
import from 'vitepress/theme'
import { } from '@nolebase/vitepress-plugin-git-changelog/client'
// Rest of the code...
export const : ThemeConfig = {
: ,
: () => {
// Rest of the code...
},
({ }) {
.()
},
}
export default Import changelog components on demand
import {
,
} from '@nolebase/vitepress-plugin-git-changelog/client'Import contributors components on demand
import {
,
} from '@nolebase/vitepress-plugin-git-changelog/client'
BeiyanYunyi
Neko
Northword