155 lines
4.7 KiB
Markdown
155 lines
4.7 KiB
Markdown
---
|
||
title: 文章变更历史
|
||
icon: radix-icons:activity-log
|
||
createTime: 2024/11/07 18:16:25
|
||
permalink: /guide/features/changelog/
|
||
---
|
||
|
||
## 概述
|
||
|
||
主题支持为文章添加 文章变更历史，以便更好的了解您的文章修改历史。
|
||
|
||
文章变更历史 通过 git 提交记录获取。
|
||
|
||
该功能由 [@vuepress/plugin-git](https://ecosystem.vuejs.press/zh/plugins/development/git.html) 提供支持。
|
||
|
||
::: warning 注意
|
||
该功能由于需要通过 `git log` 命令获取每个 md 文件的提交记录，是一个相对比较耗时的操作，特别是对于大型项目，提交记录数量较多的情况。因此该功能在开发环境中不会启用，仅在生产环境中启用。
|
||
|
||
但你仍然可以通过设置 `theme.plugins.git` 为 `true` 来启用该功能，以便在开发环境中测试。
|
||
|
||
```ts
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
theme: plumeTheme({
|
||
plugins: { git: true }
|
||
})
|
||
})
|
||
```
|
||
|
||
:::
|
||
|
||
## 使用
|
||
|
||
主题已内置 [@vuepress/plugin-git](https://ecosystem.vuejs.press/zh/plugins/development/git.html) 插件，你无需重新安装即可使用。
|
||
|
||
在主题配置文件中启用该功能:
|
||
|
||
```ts title=".vuepress/config.ts"
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
theme: plumeTheme({
|
||
// 默认 不启用，仅当 plugins.git 为 true 时生效
|
||
// 此配置在 plume.config.ts 中无效
|
||
changelog: true,
|
||
|
||
plugins: {
|
||
// 如果您在此处直接声明为 true，则表示开发环境和生产环境都启用该功能
|
||
git: process.env.NODE_ENV === 'production'
|
||
}
|
||
})
|
||
})
|
||
```
|
||
|
||
## 配置
|
||
|
||
```ts
|
||
interface ChangelogOptions {
|
||
/**
|
||
* 最大变更记录条数, 默认获取所有记录
|
||
*/
|
||
maxCount?: number
|
||
/**
|
||
* git 仓库的访问地址，例如：https://github.com/vuepress/ecosystem
|
||
*/
|
||
repoUrl?: string
|
||
/**
|
||
* 提交记录访问地址模式
|
||
*
|
||
* - `:repo` - git 仓库的访问地址
|
||
* - `:hash` - 提交记录的 hash
|
||
*
|
||
* @default ':repo/commit/:hash'
|
||
*/
|
||
commitUrlPattern?: string
|
||
/**
|
||
* issue 访问地址模式
|
||
*
|
||
* - `:repo` - git 仓库的访问地址
|
||
* - `:issue` - issue 的 id
|
||
*
|
||
* @default ':repo/issues/:issue'
|
||
*/
|
||
issueUrlPattern?: string
|
||
/**
|
||
* tag 访问地址模式,
|
||
* 默认值：':repo/releases/tag/:tag'
|
||
*
|
||
* - `:repo` - git 仓库的访问地址
|
||
* - `:tag` - tag 的名称
|
||
*
|
||
* @default ':repo/releases/tag/:tag'
|
||
*/
|
||
tagUrlPattern?: string
|
||
}
|
||
```
|
||
|
||
```ts
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
theme: plumeTheme({
|
||
changelog: {
|
||
maxCount: 10,
|
||
repoUrl: 'https://github.com/vuepress/vuepress',
|
||
commitUrlPattern: ':repo/commit/:hash',
|
||
issueUrlPattern: ':repo/issues/:issue',
|
||
tagUrlPattern: ':repo/releases/tag/:tag'
|
||
},
|
||
|
||
})
|
||
})
|
||
```
|
||
|
||
::: warning 注意
|
||
请确保 `changelog.repoUrl` 配置正确， 默认值为 [docsRepo](../../config/theme.md#docsrepo)。
|
||
|
||
主题默认适配了 `github/gitlab/gitee/bitbucket` git 托管服务的相关访问地址模式。
|
||
如果您使用的是内建的托管服务或者其他，请自行配置 `commitUrlPattern`、`issueUrlPattern`、`tagUrlPattern`。
|
||
:::
|
||
|
||
## 注意
|
||
|
||
该功能要求你的项目在 [Git 仓库](https://git-scm.com/book/en/Git-Basics-Getting-a-Git-Repository) 下，这样它才能从提交历史记录中收集信息。
|
||
|
||
**在构建站点时，你应该确保所有的提交记录是可以获取到的。**
|
||
|
||
举例来说， CI 工作流通常会在克隆你的仓库时添加 `--depth 1` 参数来避免拉取全部的提交记录，因此你需要禁用这个功能，以便该插件在 CI 可以中正常使用。
|
||
|
||
类似于 `github actions` 、`Netlify` 、 `Vercel` 等服务，默认是不会拉取全部的提交记录的。
|
||
|
||
在 `github actions` 中，可以通过添加 `--depth 0` 参数来使得 `github actions` 可以正确获取到所有的提交记录。
|
||
|
||
``` yaml title=".github/workflows/deploy.yml"
|
||
jobs:
|
||
deploy:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4 # [!code focus:3]
|
||
with: # [!code ++:2]
|
||
fetch-depth: 0
|
||
```
|
||
|
||
在 `Netlify` 、 `Vercel` 等服务中，处理方法则会相对复杂一些。这时候您可以先在 `github actions` 完成构建后
|
||
输出将产物输出到另一个单独的分支，然后在 `Netlify` 或者 `Vercel` 中直接使用该分支进行部署。
|
||
|
||
::: info
|
||
通过主题的 `cli` 工具创建的项目，在选择部署方式为 `github action` 时，构建产物会输出到 `gh_pages` 分支中，
|
||
你可以在此基础上完成 `Netlify` 或者 `Vercel` 的部署。
|
||
:::
|