配置 Vite 插件

弃用 GitChangelogMarkdownSection 插件选项的 locales 字段

我们将 locales 配置迁移到了配置 UI。

您不再需要为 GitChangelogMarkdownSection 插件设置 locales。

有关具体的迁移信息，请参阅自 v1 迁移至 v2。

除了 UI 组件，基于 Git 的页面历史记录还提供了另外两个 Vite 插件，用于数据获取和渲染。这两个插件分别是 GitChangelog 和 GitChangelogMarkdownSection。

配置 Vite 插件

是 TypeScript 用户吗？

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

jsonc

{
  "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。

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

jsonc

{
  "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"
  ]
}

`GitChangelog` 插件

还记得我们第一次介绍 GitChangelog 插件时的这部分内容吗？

typescript

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

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

在 GitChangelog 插件中，您可以配置 repoURL 选项，使其指向您的 Git 仓库托管的 URL。这是插件正常工作的唯一必要选项。

但选项并不止于此。我们还有更多选项来配置插件，以满足您的需求。

完整选项

typescript

interface Options {
    /**
   * The current working directory in which to search files.
   *
   * @default process.cwd()
   */
  ?: string
  /**
   * When fetching git logs, what files should be included?
   *
   * @default ['** /*.md', '!node_modules']
   */
  ?: string[]
  /**
   * Your repository URL.
   * Yes, you can dynamically generate it.
   *
   * @default 'https://github.com/example/example'
   */
  ?: string | 
  /**
   * A function to get the release tag URL.
   *
   * @default (commit) => `${commit.repo_url}/releases/tag/${commit.tag}`
   */
  ?: 
  /**
   * A function to get the release tags URL.
   *
   * @default (commit) => commit.tags?.map(tag => `${commit.repo_url}/releases/tag/${tag}`)
   */
  ?: 
  /**
   * A function to get the commit URL.
   *
   * @default (commit) => `${commit.repo_url}/commit/${commit.hash}`
   */
  ?: 
  /**
   * Rules to rewrite paths by patterns.
   *
   * This can be quite useful when your pages are in different directories,
   * or when they are generated at runtime according to path.ts.
   *
   * Since the plugin matches the git information for each page by comparing the local path,
   * you can override the local file path to `vitepress.useData.page.value.filePath` with this option.
   *
   * @example
   *
   * ```typescript
   * GitChangelog({
   *   rewritePathsBy: {
   *     handler: (_commit, path) => {
   *       if (path) {
   *         // path: packages/characters/src/lib1.ts
   *         if (path.startsWith('packages/characters/src/') && !path.includes('index.ts'))
   *           return `${path.replace('packages/characters/src/', '').slice(0, -3)}.md`
   *       }
   *       return path
   *     },
   *   },
   * })
   * ```
   *
   * Besides that, we offer some built-in handlers to rewrite paths by patterns:
   *
   *  - `rewritePathsByRewritingExtension(from: string, to: string)`: to rewrite paths by rewriting the extension.
   *
   * @example
   *
   * ```typescript
   * import { GitChangelog, rewritePathsByRewritingExtension } from '@nolebase/vitepress-plugin-git-changelog/vite'
   *
   * GitChangelog({
   *  rewritePathsBy: {
   *   // to rewrite `example.md` to `example.html`
   *  handler: rewritePathsByRewritingExtension('.md', '.html')
   * }
   * })
   * ```
   *
   * @see rewritePathsByRewritingExtension
   */
  ?: RewritePathsBy
  /**
   * The maximum number of git logs to fetch.
   */
  ?: number
}

`GitChangelogMarkdownSection` 插件

GitChangelogMarkdownSection 插件是一个在 Markdown 页面中注入章节的插件。可以与 GitChangelog 插件一起使用，以在页面中显示 Git 历史记录。

typescript

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

export default ({
  : [
    (), 
  ],
  // other vite configurations...
})

在幕后，这个插件的作用只是在你的 Markdown 页面中添加 <NolebaseGitContributors /> 和 <NolebaseGitChangelog /> 组件。

它确实有更多的配置选项。

完整选项

typescript

interface GitChangelogMarkdownSectionOptions {
  /**
   * The list of file names to exclude from the transformation
   *
   * @default ['index.md']
   */
  ?: string[]
  /**
   * The function to exclude the file from the transformation
   *
   * @param id - the current transforming module ID (comes from vite when transform hook is called)
   * @param context - the context object, contains several helper functions
   * @returns boolean
   * @default () => false
   */
  ?: (: string, : Context) => boolean
  /**
   * The sections options
   */
  ?: {
    /**
     * Whether to disable the changelog section
     */
    ?: boolean
    /**
     * Whether to disable the contributors section
     */
    ?: boolean
  }
}

在 Markdown 页面层级将页面排除在 `GitChangelogMarkdownSection` 的转换之外

您可以通过在页面的 frontmatter 中添加 nolebase.gitChangelog 或 gitChangelog 配置，将页面排除在 GitChangelogMarkdownSection 转换之外：

markdown

---
nolebase:
  gitChangelog: false
---

或者

markdown

---
gitChangelog: false
---

都可以。

全局地将某个页面排除在 `GitChangelogMarkdownSection` 的转换之外

通过配置 exclude 选项，可以全局地将某个页面排除在 GitChangelogMarkdownSection 的转换之外：

typescript

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

export default ({
  : [
    ({ 
      : () => .('index.md'), 
    }), 
  ],
  // other vite configurations...
})

全局禁用页面历史或贡献者章节

通过配置 sections 选项，可以在全局禁用页面历史或贡献者章节：

typescript

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

export default ({
  : [
    ({ 
      : { 
        : true, 
        : true, 
      }, 
    }), 
  ],
  // other vite configurations...
})