Getting started

Word count

1554 words

Reading time

10 minutes

Installation

Install @nolebase/vitepress-plugin-git-changelog to your project dependencies by running the following command:

@antfu/ni

ni @nolebase/vitepress-plugin-git-changelog -D

pnpm

pnpm add @nolebase/vitepress-plugin-git-changelog -D

npm

npm install @nolebase/vitepress-plugin-git-changelog -D

yarn

yarn add @nolebase/vitepress-plugin-git-changelog -D

Usage

This is roughly the most complex one to configure with!

Please pay attentions to the following configurations and steps to get started with the Git-based page histories plugin. It is not quite simple as other plugins.

It consists two major steps to integrate the Inline Links Previewing plugin into your VitePress project:

• Configure Vite plugin (data fetching, logs aggregation)
• Integrate with VitePress (UI and components)

Configure Vite plugin

There are two ways to integrate the Git-based page histories Vite plugin into your VitePress project:

1. Recommended: Use the vite option in VitePress's primary configuration file (usually located at docs/.vitepress/config.ts, file paths and extensions may be vary)
2. Create a separated Vite configuration file (e.g. vite.config.ts) in the root directory of your VitePress project

Configure Vite plugin in VitePress's config file

In VitePress's primary configuration file (not this is not a theme configuration file, it's usually located at docs/.vitepress/config.ts, file paths and extensions may be vary), we need to import both GitChangelog (data fetcher), and GitChangelogMarkdownSection (widget embedder) the plugins and configure it properly:

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

A TypeScript User?

You need to configure at least the following options:

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

And the options

• module option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses the ESNext-compatible module format by default.
• moduleResolution option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter a Cannot find module ... or its corresponding type declarations error you may need to set moduleResolution to Bundler.

If you want more configurations, you can refer to the following example:

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

import { defineConfig } from 'vitepress'
import { 
  GitChangelog, 
  GitChangelogMarkdownSection, 
} from '@nolebase/vitepress-plugin-git-changelog/vite'

// https://vitepress.dev/reference/site-config
export default defineConfig({
  vite: { 
    plugins: [ 
      GitChangelog({ 
        // Fill in your repository URL here
        repoURL: () => 'https://github.com/nolebase/integrations', 
      }), 
      GitChangelogMarkdownSection(), 
    ],
  }, 
  lang: 'en',
  title: 'Site Name',
  themeConfig: {
    // rest of the options...
  }
  // rest of the options...
})

Configure Vite plugin in a separated Vite configuration file

Ensure vite.config.ts is created

If you understand what vite.config.ts is already and have created it, you can skip this preparation step and jump to the next step Configure plugin in vite.config.ts.

New to vite.config.ts is?

First of all, vite.config.ts is a configuration file for Vite, the build tool that VitePress is built on. It allows developers to build and transform the assets, content and data in the project.

Even though VitePress itself contains entire set of Vite options in its primary configuration file (not this is not a theme configuration file, it's usually located at docs/.vitepress/config.ts, file paths and extensions may be vary), these options, and yet, the vite.config.ts are identical in terms of configurations.

However, due to the order of plugins it registered, it's not enough to transform the needed data and logs if we install the Git-based page histories plugin in this way.

Therefore, please create a separated vite.config.ts file in the root directory of your VitePress project:

Where is the root directory of VitePress project?

VitePress project's root directory is where the parent directory of .vitepress directory is.

For example:

.
├── docs
│   ├── .vitepress
│   │   ├── config.ts
│   │   └── theme
│   │       └── index.ts
│   └── README.md

In this case, the root directory is docs.

.
├── .vitepress
│   ├── config.ts
│   └── theme
│       └── index.ts
└── README.md

In this case, the root directory is ./.

touch vite.config.ts

Configure plugin in vite.config.ts

In the standalone Vite configuration file (e.g. vite.config.ts) file we have under our root directory, we need to import both GitChangelog (data fetcher), and GitChangelogMarkdownSection (widget embedder) the plugins and configure it properly:

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

A TypeScript User?

You need to configure at least the following options:

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

And the options

• module option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses the ESNext-compatible module format by default.
• moduleResolution option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter a Cannot find module ... or its corresponding type declarations error you may need to set moduleResolution to Bundler.

If you want more configurations, you can refer to the following example:

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

import { join } from 'node:path'
import { defineConfig } from 'vite'
import { 
  GitChangelog, 
  GitChangelogMarkdownSection, 
} from '@nolebase/vitepress-plugin-git-changelog/vite'

export default defineConfig(() => {
  return {
    plugins: [ 
      GitChangelog({ 
        // Fill in your repository URL here
        repoURL: () => 'https://github.com/nolebase/integrations', 
      }), 
      GitChangelogMarkdownSection(), 
    ]
    // other vite configurations...
  }
})

Integrate with VitePress theme

Now, let's integrate the Git-based page histories UI widgets into your VitePress project.

In VitePress's theme configuration file (note that it's not a configuration file, it's usually located at docs/.vitepress/theme/index.ts, file paths and extensions may be vary), install the Vue plugin and use the components:

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

A TypeScript User?

You need to configure at least the following options:

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

And the options

• module option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses the ESNext-compatible module format by default.
• moduleResolution option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter a Cannot find module ... or its corresponding type declarations error you may need to set moduleResolution to Bundler.

If you want more configurations, you can refer to the following example:

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

docs/.vitepress/theme/index.ts

import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import type { Theme as ThemeConfig } from 'vitepress'
import { 
  NolebaseGitChangelogPlugin 
} from '@nolebase/vitepress-plugin-git-changelog/client'

import '@nolebase/vitepress-plugin-git-changelog/client/style.css'

export const Theme: ThemeConfig = {
  extends: DefaultTheme,
  Layout: () => {
    // other configurations...
  },
  enhanceApp({ app }) {
    app.use(NolebaseGitChangelogPlugin)  
  },
}

export default Theme

When will the Git page history information be generated? Configure deployment tools and CI/CD

What is CI/CD?

Usually, documents using Git-based page history plugin will integrate with GitHub Actions or GitLab's CI/CD Pipelines to automate the building process against documentations in the dedicated environment after pushing change commits instead of asking users to execute commands manually and carry out complex construction processes when needed to deploy. You can read more here: Platform Guides - VitePress

Tools like GitHub Actions and GitLab's CI/CD Pipelines provided by GitHub and GitLab to automate the process of building sites, artifacts are one of the step called [CD (Continuous Deployment)](Continuous deployment - Wikipedia) and is part of the larger concept called CI/CD (continuous integration/continuous deployment .

Of course, the CI/CD capabilities of the two Git code hosting platforms listed above are only the tip of the iceberg. In fact, there are other tools out there:

• [Netlify's build hook] (https://docs.netlify.com/configure-builds/build-hooks/)
• [Git integration of Cloudflare Pages] (https://developers.cloudflare.com/pages/configuration/git-integration/ )
• [Vercel's GitHub integration] (https://vercel.com/docs/deployments/git/vercel-for-github)
• CircleCI

These are platforms that provide static site hosting plus CI/CD pipeline features. In summary, they allows users to automatically generate static sites according to pre-configured commands and processing pipelines after pushing commits against files.

CI/CD will be run in an dedicated server environment, therefore all the building processes, building commands, and environments are and reprodusable environment.

Whenever contributors / authors commit a file through the git command or Git client, or merge the committed files modified from Pull Request, a "commit" event will be triggered. Generally, CI/CD will be based on such "commit" event where a new, dedicated build environment got created.

CI/CD is triggered by Git commits, and Git-based page history relies on Git commits, so when using a tool like CI/CD, we need to check and configure it before using it to make sure that Git logs are fetched in full or quantitatively, or else there will be no way to fetch Git logs correctly.

Build on GitHub Actions

When using it with Github Actions, we only need to add the configuration of fetch-depth: 0 to the with parameter of actions/checkout to ensure that it is in CI/CD The Git log obtained in the environment contains all the information:

name: Build Docs

on:
  push:
    branches:
      - 'main'

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout codes
        uses: actions/checkout@v4
        with: 
          fetch-depth: 0

      # ... other steps

Contributor information

The contributor information (such as name and email address) is resolved from the commit author information.

If the commit email address is a GitHub-provided no-reply email (like <user>@users.noreply.github.com), then it is used for determaining the GitHub username, which is then used for getting the profile picture from GitHub, as well as linking to the GitHub profile (unless overriden by the mapAuthors option).

By default, Gravatar is used for getting a profile picture based on an email address.

Build on Netlify

By default, Netlify can get all Git logs during the CI/CD build.

Build on Cloudflare Pages

The CI/CD pipeline feature of Cloudflare Pages does not provide a way to fetch all Git logs. The only solution is building sites in a controlled environment like GitHub Actions or GitLab CI/CD Pipeline then deploy the artifacts through Cloudflare's official wrangler CLI tool.

For example, you can use the GitHub Actions plugin pages-action with the fetch-depth: 0 parameter described in [build on GitHub Actions](#build on -github -actions-) with the fetch-depth: 0 parameter described in Build on GitHub Actions.

Build on Vercel

In Vercel's built-in CI/CD environment, by default, you cannot access the complete Git log information^[1]. You can obtain full Git commit information by setting the environment variable VERCEL_DEEP_CLONE=true. Note that this environment variable is not a stable public API and will be removed at some point in the future^[2].

A more stable but slightly complex solution is to first build in a controlled environment such as GitHub Actions or GitLab CI/CD Pipelines, and then deploy using Vercel's official vercel CLI tool.

Troubleshooting

Encountered Cannot find module ... or its corresponding type declarations error?

If you are encountering this error with Nolebase Integrations packages inside of .ts or .vue files, you may need to configure the moduleResolution option in your tsconfig.json file.

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

If the error persists, please submit a GitHub issue for further assistance and troubleshooting.

Contributors

Neko Rizumu

三咲智子 Kevin Deng

Gilad S.

Glom_

Changelog

Last edited about 1 month ago

View full history

a02e003-docs(git changelog): how to build in vercel

ab4828a-docs: fix incorrect snippeted imported (#303)

4dad600-feat(git changelog): resolve contributors' GitHub profile URL (#294)

37e2bbf-docs(git-changelog): added documentations about git changelog with CI/CD setup (#234)

d2c7191-docs: fixed a typo in git-changelog, styles.css -> style.css (#174)

526728a-docs: refined docs

917fab3-feat(git-changelog): added rewritePathsBy.handler support to dynamically transform paths (#160)

e00b95a-feat(git-changelog): added i18n capabilities, added more fancy documentations (#156)

---

1. Access git logs in build process · vercel/vercel · Discussion #4101 ↩︎

2. To tell Vercel to deep clone by setting an env var to VERCEL_DEEP_CLONE=1 · vercel/turborepo · Discussion #800 ↩︎