快速上手

安装

通过运行以下命令将 @nolebase/vitepress-plugin-git-changelog 安装到您的项目依赖项中：

@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

使用

这是配置最复杂的插件之一！

请注意以下配置和步骤，以开始使用基于 Git 的页面历史插件。与其他插件相比，这并不是那么简单。

将基于 Git 的页面历史插件集成到您的 VitePress 项目中包括两个主要步骤：

• 配置 Vite 插件（数据获取、日志聚合）
• 与 VitePress 集成（UI 和组件）

配置 Vite 插件

有两种将基于 Git 的页面历史 Vite 插件集成到您的 VitePress 项目中的方法：

1. 推荐：在 VitePress 的主要配置文件中使用 vite 选项（通常位于 docs/.vitepress/config.ts，文件路径和扩展名可能会有所不同）
2. 在 VitePress 项目的根目录中创建一个单独的 Vite 配置文件（例如 vite.config.ts）

在 VitePress 的配置文件中配置 Vite 插件

请在你的 VitePress 核心配置文件 中（注意不是主题配置文件，通常为 docs/.vitepress/config.ts，文件路径和拓展名也许会有区别）的根字段中添加 Vite 选项，并导入并配置 GitChangelog（数据获取）和 GitChangelogMarkdownSection（小部件嵌入）插件：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

是 TypeScript 用户吗？

至少需要配置下面的几个选项：

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

其中的

• module 选项指定了 JavaScript/TypeScript 的模块格式，Nolebase Integrations 默认使用与 ESNext 相兼容的模块格式。
• moduleResolution 选项指定了模块解析策略，因为所有的 Nolebase Integrations 插件都遵循最新的 ECMAScript 规范与导出声明，如果你遇到了 Cannot find module ... or its corresponding type declarations 的错误，你可能需要将 moduleResolution 设置为 Bundler。

如果你想要更多的配置，可以参考下面的示例：

{
  "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 {  } from 'vitepress'
import { 
  , 
  , 
} from '@nolebase/vitepress-plugin-git-changelog/vite'

// https://vitepress.dev/reference/site-config
export default ({
  : { 
    : [ 
      ({ 
        // 填写在此处填写您的仓库链接
        : () => 'https://github.com/nolebase/integrations', 
      }), 
      (), 
    ],
  }, 
  : 'zh-CN',
  : '站点名称',
  : {
    // rest of the options...
  }
  // rest of the options...
})

在单独的 Vite 配置文件中配置 Vite 插件

确保已创建 vite.config.ts

如果您已经了解 vite.config.ts 是什么并且已经创建了它，您可以跳过此准备步骤，直接跳转到下一步在 vite.config.ts 中配置插件。

首次接触 vite.config.ts？

首先，vite.config.ts 是一个为 Vite 构建工具的配置文件。VitePress 是基于 Vite 构建的，它允许开发人员构建和转换项目中的资产、内容和数据。

尽管 VitePress 本身包含了整套 Vite 选项的配置在其主要配置文件中（这不是一个主题配置文件，通常位于 docs/.vitepress/config.ts，文件路径和扩展名可能会有所不同），这些选项与 vite.config.ts 在配置方面是相同的。

然而，由于插件注册的顺序，如果我们以这种方式安装基于 Git 的页面历史插件，它将无法转换所需的数据和日志。

因此，请在您的 VitePress 项目的根目录中创建一个单独的 vite.config.ts 文件：

哪里是 VitePress 项目的根目录？

VitePress 项目的根目录是 .vitepress 目录的父目录。

例如，如果您的 VitePress 项目的目录结构如下所示：

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

在这种情况下，根目录是 docs。

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

在这种情况下，根目录是 ./。

touch vite.config.ts

在 vite.config.ts 中配置插件

在位于项目根目录的独立的 Vite 配置文件（也就是 vite.config.ts 中），我们需要导入 GitChangelog（数据获取）和 GitChangelogMarkdownSection（小部件嵌入）插件并进行正确配置：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

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

export default (() => {
  return {
    : [ 
      ({ 
        // 填写在此处填写您的仓库链接
        : () => 'https://github.com/nolebase/integrations', 
      }), 
      (), 
    ]
    // 其他 Vite 配置...
  }
})

与 VitePress 主题集成

现在，让我们将基于 Git 的页面历史 UI 小部件集成到您的 VitePress 项目中。

在 VitePress 的主题配置文件（请注意，这与上面提及的配置文件并非是一个文件，主题配置文件通常位于 docs/.vitepress/theme/index.ts，文件路径和扩展名可能会有所不同），安装 Vue 插件并使用组件：

是 TypeScript 用户吗？

至少需要配置下面的几个选项：

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

其中的

• module 选项指定了 JavaScript/TypeScript 的模块格式，Nolebase Integrations 默认使用与 ESNext 相兼容的模块格式。
• moduleResolution 选项指定了模块解析策略，因为所有的 Nolebase Integrations 插件都遵循最新的 ECMAScript 规范与导出声明，如果你遇到了 Cannot find module ... or its corresponding type declarations 的错误，你可能需要将 moduleResolution 设置为 Bundler。

如果你想要更多的配置，可以参考下面的示例：

{
  "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 {  } from 'vue'
import  from 'vitepress/theme'
import type {  as ThemeConfig } from 'vitepress'
import { 
   
} from '@nolebase/vitepress-plugin-git-changelog/client'

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

export const : ThemeConfig = {
  : ,
  : () => {
    // 其他配置
  },
  ({  }) {
    .()  
  },
}

export default 

错误排查

遭遇了 Cannot find module ... or its corresponding type declarations 错误？

如果有任何的 Nolebase Integrations 插件在 .ts 或 .vue 文件中出现此错误，你可能需要在 tsconfig.json 文件中配置 moduleResolution 选项：

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

如果错误仍然存在，请提交 GitHub issue 以获得进一步帮助并排除故障。

贡献者

Neko Northword

Glom_

页面历史

最后编辑于 13 天前查看完整历史

69909-feat(git-changelog): support git submodule (#189)

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

52672-docs: refined docs

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

d6539-docs(git-changelog): updated docs

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