Configure Vite plugins

Word count

964 words

Reading time

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

Configure Vite plugins

A TypeScript User?

You need to configure at least the following options:

jsonc

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

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` plugin

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

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

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.

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

Full list of options

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` 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.

typescript

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

export default ({
  : [
    (), 
  ],
  // 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

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

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:

markdown

---
nolebase:
  gitChangelog: false
---

markdown

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

typescript

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

export default ({
  : [
    ({ 
      : () => .('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:

typescript

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

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