配置 Vite 插件

字数

1741 字

阅读时间

10 分钟

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

配置 Vite 插件

是 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。这是插件正常工作的唯一必要选项。

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

完整选项

interface Options {
  /**
   * When fetching git logs, what directories should be included?
   */
  includeDirs?: string[]
  /**
   * Your repository URL.
   * Yes, you can dynamically generate it.
   *
   * @default 'https://github.com/example/example'
   */
  repoURL?: string | ((commit: Commit) => string)
  /**
   * A function to get the release tag URL.
   *
   * @default (commit) => `${commit.repo_url}/releases/tag/${commit.tag}`
   */
  getReleaseTagURL?: (commit: Commit) => string
  /**
   * A function to get the commit URL.
   *
   * @default (commit) => `${commit.repo_url}/commit/${commit.hash}`
   */
  getCommitURL?: (commit: Commit) => string
  /**
   * A map that contains rewrite rules of paths.
   *
   * This is quite useful when you have your pages in a different directory than the base url after deployed since the
   * data will be calculated again on the client side.
   *
   * For example:
   *  - We have a page at `docs/pages/en/integrations/page.md`
   *  - And we will deploy it to `https://example.com/en/integrations/page`
   *
   * Then you can set the rewrite paths like this:
   * ```json
   * {
   *  "docs/": ""
   * }
   * ```
   *
   * This will rewrite the path to `en/integrations/page.md`
   * Which is the correct path for the deployed page and runtime scripts to work properly.
   *
   * Note: in runtime, which is client side, the final extension will be replaced with `.md` if the extension is `.html`.
   */
  rewritePaths?: Record<string, string>
  /**
   * Rules to rewrite paths by patterns.
   *
   * Same as `rewritePaths`, but it can be a function that returns a promise or plain value.
   * 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
  /**
   * The maximum number of concurrent processes to fetch git logs.
   */
  maxConcurrentProcesses?: 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 locales options
   */
  locales?: Record<string, Locale>
  /**
   * The getter function to get the title of the changelog section
   *
   * @param code - raw markdown code (comes from vite when transform hook is called)
   * @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 string
   * @default () => 'Changelog'
   */
  getChangelogTitle?: (code: string, id: string, context: Context) => string
  /**
   * The getter function to get the title of the contributors section
   *
   * @param code - raw markdown code (comes from vite when transform hook is called)
   * @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 string
   * @default () => 'Contributors'
   */
  getContributorsTitle?: (code: string, id: string, context: Context) => string
  /**
   * 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
  }
}

国际化

GitChangelogMarkdownSection 插件支持国际化。你可以配置 locales 选项来提供章节标题的翻译：

为什么又有国际化配置了？还是在 Vite 里面的？认真的？

VitePress 有一个名为大纲的功能，它是通过读取一个页面中的所有标题然后基于此生成的侧边栏导航。 而为了能让页面历史和贡献者章节出现在大纲列表中，我们必须先将这些部分注入 Markdown，然后再交给 VitePress 渲染成 HTML

但是，与在 Vite 插件中直接操作或通过 Remark API 操作相比，在 markdown-it 的抽象语法树（AST）中操作 Markdown 会更加困难，不过这又是另一个话题了。

总之，我们必须在 Markdown 渲染成 HTML 之前，先将部分内容注入 Markdown，并提供国际化支持。

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

export default defineConfig({
  plugins: [
    GitChangelogMarkdownSection({ 
      locales: { 
        'zh-CN': { 
          gitChangelogMarkdownSectionTitles: { 
            changelog: '文件历史', 
            contributors: '贡献者', 
          }, 
        }, 
        'en': { 
          gitChangelogMarkdownSectionTitles: { 
            changelog: 'File History', 
            contributors: 'Contributors', 
          }, 
        }, 
      }, 
    }), 
  ],
  // other vite configurations...
})

或者直接动态生成

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

export default defineConfig({
  plugins: [
    GitChangelogMarkdownSection({ 
      getChangelogTitle: (_, __, { helpers }): string => {
        if (helpers.idStartsWith(join('pages', 'en')))
          return 'File History'
        if (helpers.idStartsWith(join('pages', 'zh-CN')))
          return '文件历史'

        return 'File History'
      },
      getContributorsTitle: (_, __, { helpers }): string => {
        if (helpers.idStartsWith(join('pages', 'en')))
          return 'Contributors'
        if (helpers.idStartsWith(join('pages', 'zh-CN')))
          return '贡献者'

        return 'Contributors'
      },
    }), 
  ],
  // other vite configurations...
})

在 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

Rizumu

文件历史

最后编辑于 大约 18 小时前查看完整历史

v2.0.0-rc6

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

v2.0.0-rc5

52672-docs: refined docs

v2.0.0-rc1

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

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