Changelog
Overview
The theme supports adding article changelogs to better track the modification history of your articles.
Article changelogs are obtained through git commit history.
This feature is powered by @vuepress/plugin-git.
Note
This feature relies on the git log command to retrieve commit history for each markdown file, which can be relatively time-consuming, especially for large projects with extensive commit histories. Therefore, this feature is not enabled in development environments by default and is only enabled in production environments.
However, you can still enable it in development environments by setting theme.plugins.git to true for testing purposes.
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
plugins: { git: true }
})
})Usage
The theme has built-in support for the @vuepress/plugin-git plugin, so you can use it without reinstalling.
Enable this feature in the theme configuration file:
import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
export default defineUserConfig({
theme: plumeTheme({
// Disabled by default, only takes effect when plugins.git is true
// This configuration is invalid in plume.config.ts
changelog: true,
plugins: {
// If you declare it directly as true here, it means the feature is enabled in both development and production environments
git: process.env.NODE_ENV === 'production'
}
})
})Configuration
interface ChangelogOptions {
/**
* Maximum number of change records, defaults to all records
*/
maxCount?: number
/**
* Git repository URL, e.g., https://github.com/vuepress/ecosystem
*/
repoUrl?: string
/**
* Commit URL pattern
*
* - `:repo` - Git repository URL
* - `:hash` - Commit hash
*
* @default ':repo/commit/:hash'
*/
commitUrlPattern?: string
/**
* Issue URL pattern
*
* - `:repo` - Git repository URL
* - `:issue` - Issue ID
*
* @default ':repo/issues/:issue'
*/
issueUrlPattern?: string
/**
* Tag URL pattern
* Default: ':repo/releases/tag/:tag'
*
* - `:repo` - Git repository URL
* - `:tag` - Tag name
*
* @default ':repo/releases/tag/:tag'
*/
tagUrlPattern?: string
}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'
},
})
})Note
Ensure that changelog.repoUrl is correctly configured. The default value is docsRepo.
The theme by default adapts to the URL patterns of git hosting services like GitHub, GitLab, Gitee, and Bitbucket. If you're using a self-hosted service or others, please configure commitUrlPattern, issueUrlPattern, and tagUrlPattern accordingly.
Notes
This feature requires your project to be under a Git repository so it can collect information from the commit history.
When building your site, you should ensure all commit records are accessible.
For example, CI workflows typically add the --depth 1 parameter when cloning your repository to avoid fetching all commit history. In this case, you need to fetch the full commit history instead (remove --depth 1) so the plugin can work properly in CI.
Services like GitHub Actions, Netlify, and Vercel do not fetch all commit history by default.
In GitHub Actions, you should configure fetch-depth: 0 for actions/checkout, i.e. fetch the full commit history.
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0For services like Netlify and Vercel, the processing method is relatively more complex. In such cases, you can first complete the build in GitHub Actions and output the build artifacts to a separate branch, then use that branch for deployment in Netlify or Vercel.
Info
For projects created via the theme's cli tool, when selecting the deployment method as GitHub Action, the build artifacts are output to the gh_pages branch. You can base your Netlify or Vercel deployment on this branch.
