配置 Vite 插件

字数

1463 字

阅读时间

8 分钟

弃用 GitChangelogMarkdownSection 插件选项的 locales 字段

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

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

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

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

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

配置 GitChangelog 插件

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

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...
  }
})

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

选项 mapContributors - 为贡献者添加数据映射

配置选项中的 mapContributors 字段用于映射贡献者信息，可以用来将获取到的 Git 的日志信息中的包括名称和邮箱的贡献者信息映射为另一个贡献者。

如果我们假设有如下的 Git 日志：

commit 1
Author: John Doe <[email protected]>
Date:   Fri Oct 1 12:00:00 2021 +0800

    Add a new feature

commit 2
Author: John Doe <[email protected]>

    Fix a bug

现在我们有两个来自同一个人的提交，只有电子邮件地址不同。在不进行任何配置的默认情况下，插件会将它们视为两个不同的贡献者。 这种情况通常是因为你或者其他贡献者更改了自己的电子邮件地址。

要解决这个问题，我们可以使用 mapAuthors 选项：

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',
        mapAuthors: [ 
          { 
            name: 'John Doe', 
            username: 'john_doe', 
            mapByEmailAliases: ['[email protected]'] 
          } 
        ] 
      }), 
      GitChangelogMarkdownSection(),
    ]
    // other vite configurations...
  }
})

完整选项

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

完整选项

interface GitChangelogOptions {
    /**
   * The current working directory in which to search files.
   *
   * @default process.cwd()
   */
  cwd?: string
  /**
   * When fetching git logs, what files should be included?
   *
   * @default ['** /*.md', '!node_modules']
   */
  include?: string[]
  /**
   * Map authors
   */
  mapAuthors?: Author[]
  /**
   * Your repository URL.
   * Yes, you can dynamically generate it.
   *
   * @default 'https://github.com/example/example'
   */
  repoURL?: string | CommitToStringHandler
  /**
   * A function to get the release tag URL.
   *
   * @default (commit) => `${commit.repo_url}/releases/tag/${commit.tag}`
   */
  getReleaseTagURL?: CommitToStringHandler
  /**
   * A function to get the release tags URL.
   *
   * @default (commit) => commit.tags?.map(tag => `${commit.repo_url}/releases/tag/${tag}`)
   */
  getReleaseTagsURL?: CommitToStringsHandler
  /**
   * A function to get the commit URL.
   *
   * @default (commit) => `${commit.repo_url}/commit/${commit.hash}`
   */
  getCommitURL?: CommitToStringHandler
  /**
   * 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?: RewritePathsBy
  /**
   * The maximum number of git logs to fetch.
   */
  maxGitLogCount?: number
}

配置 GitChangelogMarkdownSection 插件

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

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

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

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

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

完整选项

interface GitChangelogMarkdownSectionOptions {
  /**
   * The list of file names to exclude from the transformation
   *
   * @default ['index.md']
   */
  excludes?: 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
   */
  exclude?: (id: string, context: Context) => boolean
  /**
   * The sections options
   */
  sections?: {
    /**
     * Whether to disable the changelog section
     */
    disableChangelog?: boolean
    /**
     * Whether to disable the contributors section
     */
    disableContributors?: boolean
  }
}

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

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

---
nolebase:
  gitChangelog: false
---

或者

---
gitChangelog: false
---

都可以。

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

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

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

export default defineConfig({
  plugins: [
    GitChangelogMarkdownSection({ 
      exclude: (id) => id.endsWith('index.md'), 
    }), 
  ],
  // other vite configurations...
})

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

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

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

export default defineConfig({
  plugins: [
    GitChangelogMarkdownSection({ 
      sections: { 
        disableChangelog: true, 
        disableContributors: true, 
      }, 
    }), 
  ],
  // other vite configurations...
})

贡献者

Neko Northword BeiyanYunyi Rizumu

页面历史

最后编辑于 大约 2 个月前

查看完整历史

59543b2-refactor!: mv data processing to vite side (#269)

04fb100-refactor(git-changelog): migrate i18n to ui config (#213)

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

e109948-fix(git-changelog): incorrect order of commit transform (#180)

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)