Skip to content
CONSTRUCTING

Configuration

Word count
1874 words
Reading time
12 minutes

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

typescript
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

typescript
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:

plaintext
commit 1
Author: John Doe <john.doe@example.com>
Date:   Fri Oct 1 12:00:00 2021 +0800

    Add a new feature

commit 2
Author: John Doe <john.doe@anothersite.com>

    Fix a bug

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 mapAuthors field in the configuration options to map the contributors' information:

typescript
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', 
          : ['john.doe@anothersite.com'] 
        } 
      ] 
    }) 

    // 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
typescript
/**
 * 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

typescript
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
typescript
/**
 * 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:

typescript
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

typescript
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:

typescript
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

typescript
import {
  ,  
} from '@nolebase/vitepress-plugin-git-changelog/client'

Import contributors components on demand

typescript
import {
  ,  
} from '@nolebase/vitepress-plugin-git-changelog/client'

Contributors

The avatar of contributor named as BeiyanYunyi BeiyanYunyi
The avatar of contributor named as Neko NekoThe avatar of contributor named as Northword Northword

Changelog