Configure Vite plugins

Word count

1198 words

Reading time

8 minutes

Deprecating the locales field of GitChangelogMarkdownSection plugin options

We migrated the locales configurations to UI config. You no longer need to set locales for GitChangelogMarkdownSection plugin.

For information, please refer to Migrate from v1 to v2.

Besides the UI widget components, Git-based page histories offer another two Vite plugins for data fetching and rendering. These plugins are GitChangelog and GitChangelogMarkdownSection.

A TypeScript User?

You need to configure at least the following options:

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

And the options

• module option specifies the JavaScript/TypeScript module format, and Nolebase Integrations uses the ESNext-compatible module format by default.
• moduleResolution option specifies the module resolution policy, since all Nolebase Integrations plugins follow the latest ECMAScript specifications and export declarations, if you encounter a Cannot find module ... or its corresponding type declarations error you may need to set moduleResolution to Bundler.

If you want more configurations, you can refer to the following example:

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

Configure GitChangelog plugin

Remember this part back at the time where we first introduced the GitChangelog plugin?

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

In the GitChangelog plugin, you can configure the repoURL option to point to your repository URL. This is the only required option for the plugin to work properly.

Option mapAuthors - Map contributors' information

The mapAuthors field in the configuration options is used to map the contributors' information. You can provide the mapAuthors field in the configuration options to map the contributors' information, including the display name, avatar, email, social links, and aliases.

Let's say we have these logs:

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

We now have two commits from the same person, with only the email address is different. By default, the plugin will treat them as two different contributors. Such case happens when you changed your name or email address in the past.

To solve this, you can provide the mapAuthors field in the configuration options to map the contributors' information:

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

All options

But the options don't stop there. We have more options to configure the plugin to fit your needs.

Full list of options

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
}

Configure GitChangelogMarkdownSection plugin

The GitChangelogMarkdownSection plugin is a plugin that helps you to inject the Markdown sections into your VitePress pages. It's a plugin that works with the GitChangelog plugin to provide the data for the Markdown sections.

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

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

Behind the scene, what this plugin does it simply appending <NolebaseGitContributors /> and <NolebaseGitChangelog /> components to your Markdown pages.

It does have more options to configure.

Full list of options

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

Excluding a page from the transformation of GitChangelogMarkdownSection

You can exclude a page from the transformation of GitChangelogMarkdownSection by adding the nolebase.gitChangelog or gitChangelog frontmatter to the page:

---
nolebase:
  gitChangelog: false
---

or

---
gitChangelog: false
---

Globally exclude a page from the transformation of GitChangelogMarkdownSection

You can globally exclude a page from the transformation of GitChangelogMarkdownSection by configuring the exclude option:

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

Globally disable the changelog or contributors section

You can globally disable the changelog or contributors section by configuring the sections option:

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

Contributors

Neko Northword BeiyanYunyi

Changelog

Last edited about 1 month ago

View full history

a77cb30-feat(index): new plugin vitepress-plugin-index (#328)

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)

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)