vitepress-tuck

English | 简体中文

A low-barrier, extensible plugin development library and plugin ecosystem for VitePress

Overview

vitepress-tuck is a plugin development library and plugin collection designed for VitePress. It provides a clean, unified plugin interface and configuration merging mechanism, significantly lowering the barrier to developing VitePress plugins while offering a more user-friendly integration experience.

Design Philosophy

• Low Barrier — Plugin developers only need to focus on core logic; no need to handle complex VitePress configuration merging and lifecycle orchestration.
• Easy Integration — Plugin users simply pass a plugins array to defineConfig, and plugins automatically handle configuration injection.
• Progressive Compatibility — All plugins work with both vitepress-tuck and native VitePress integration.

Quick Start

Installation

# npm
npm install -D vitepress vitepress-tuck
# pnpm
pnpm add -D vitepress vitepress-tuck
# yarn
yarn add -D vitepress vitepress-tuck
# bun
bun add -D vitepress vitepress-tuck

Using in Configuration

Replace VitePress's defineConfig with vitepress-tuck's defineConfig:

// .vitepress/config.ts
import { defineConfig } from 'vitepress-tuck'

export default defineConfig({
  plugins: [
    // Add plugins here
  ],
  // Other VitePress config options ...
})

defineConfig is fully compatible with all parameters of VitePress's native defineConfig, with the additional plugins option.

Client Code Injection

In .vitepress/theme/index.ts, import virtual:enhance-app to automatically inject plugin client code:

// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import enhanceApp from 'virtual:enhance-app'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    enhanceApp(ctx)
  },
} satisfies Theme

virtual:enhance-app is a virtual module provided by vitepress-tuck that automatically collects and merges all plugins' client configurations.

For TypeScript support, add type references in tsconfig.json:

{
  "compilerOptions": {
    "types": ["vitepress-tuck/client-types"]
  }
}

Auto Components

vitepress-tuck integrates unplugin-vue-components as a built-in plugin, enabling automatic on-demand component importing for .vue and .md files — no manual import or registration required. Plugins can declare their Vue components via the componentResolver field, and users can use them directly in Markdown or Vue files.

You can customize the behavior via the components option:

// .vitepress/config.ts
import { defineConfig } from 'vitepress-tuck'

export default defineConfig({
  components: {
    // Any unplugin-vue-components options, e.g.:
    dirs: ['src/components'],
  },
  plugins: [],
})

Plugin Ecosystem

All plugins are built on vitepress-tuck while remaining compatible with native VitePress.

Plugin	Description
vitepress-plugin-abbr	Add abbreviation support to VitePress
vitepress-plugin-annotation	Add annotation support to VitePress
vitepress-plugin-caniuse	Embed https://caniuse.com browser compatibility data
vitepress-plugin-code-collapse	provide code block collapsed lines feature
vitepress-plugin-code-tree	Render code tree structure in your VitePress site
vitepress-plugin-codepen	Embed codepen in your Vitepress site
vitepress-plugin-collapse	Render collapsible sections in your VitePress site site.
vitepress-plugin-field	Render structured API fields and properties documentation in your VitePress site
vitepress-plugin-file-tree	Render file tree structure in your VitePress site
vitepress-plugin-icons	Provide icons for vitepress with iconify / iconfont / fontAwesome
vitepress-plugin-jsfiddle	Embed JSFiddle in your VitePress site
vitepress-plugin-mark	Add mark (highlight) support to your VitePress site
vitepress-plugin-mermaid-tuck	Render Mermaid diagrams in your VitePress site
vitepress-plugin-npm-to	npm commands are automatically converted to pnpm / yarn / bun / deno commands
vitepress-plugin-obsidian	Obsidian-style Markdown syntax (Wiki links, Callout, embeds, comments)
vitepress-plugin-pdf	Embed PDF files in your VitePress site
vitepress-plugin-plantuml	Render PlantUML diagrams in your VitePress site
vitepress-plugin-plot	Add spoiler/hidden text with !!text!! syntax. Text is masked until hovered or clicked
vitepress-plugin-qrcode	Generate QR codes in your VitePress site
vitepress-plugin-repo-card	Add repository (github/gitee) card in your VitePress site
vitepress-plugin-stackblitz	Embed StackBlitz projects in your VitePress site
vitepress-plugin-steps	Render ordered/unordered lists as numbered steps with badges and connecting lines
vitepress-plugin-video	Multi-platform video embedding（Bilibili、YouTube、AcFun、ArtPlayer）
vitepress-plugin-watermark	Add watermark to your VitePress site

Developing Plugins

Creating a VitePress plugin with vitepress-tuck is straightforward:

// src/node/index.ts
import { definePlugin } from 'vitepress-tuck'

export default definePlugin((options?: MyPluginOptions) => ({
  name: 'vitepress-plugin-example',

  // Client configuration: auto-injected into virtual:enhance-app
  client: {
    imports: [
      'import "vitepress-plugin-example/style.css"',
    ],
    enhance: 'enhanceAppWithExample',
  },

  // Component resolver: declare components for auto on-demand import
  componentResolver: ['MyComponent', 'OtherComponent'],

  // Markdown configuration: register markdown-it plugins
  markdown: {
    config: (md) => {
      md.use(yourMarkdownItPlugin, options?.markdownOptions)
    },
  },

  // Vite configuration
  vite: {
    plugins: [yourVitePlugin(options?.viteOptions)],
    ssr: {
      noExternal: ['vitepress-plugin-example'],
    },
  },

  // VitePress lifecycle hooks
  buildEnd: (siteConfig) => { /* ... */ },
  transformHead: (context) => { /* ... */ },
  transformHtml: (code, id, context) => { /* ... */ },
  transformPageData: (pageData, context) => { /* ... */ },
  postRender: (context) => { /* ... */ },
}))

Development Resources

• Use vitepress-plugin-toolkit which provides createEmbedRuleBlock, createContainerPlugin, createContainerSyntaxPlugin and other utilities for quickly building markdown-it plugins.
• See the full API reference for VitepressPlugin type definitions.
• Refer to existing plugins in this repository as development examples.

Wrapping Existing Plugins

You can easily wrap any existing plugin logic into a vitepress-tuck compatible form using definePlugin:

import { definePlugin } from 'vitepress-tuck'
import { groupIconMdPlugin, groupIconVitePlugin } from 'vitepress-plugin-group-icons'

export default definePlugin(() => ({
  name: 'vitepress-plugin-group-icons',
  client: {
    imports: ['import \'virtual:group-icons.css\''],
  },
  markdown: {
    config: (md) => {
      md.use(groupIconMdPlugin)
    },
  },
  vite: {
    plugins: [groupIconVitePlugin()],
    ssr: {
      noExternal: ['vitepress-plugin-group-icons'],
    },
  },
}))

Standalone Plugin Usage

All plugins in this project can also be used independently without vitepress-tuck, directly in native VitePress:

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { qrcodePlugin } from 'vitepress-plugin-qrcode'

export default defineConfig({
  markdown: {
    config(md) {
      md.use(qrcodePlugin)
    },
  },
  vite: {
    plugins: [
      // vite config...
    ],
  },
})

// .vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import { enhanceAppWithQrcode } from 'vitepress-plugin-qrcode/client'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    enhanceAppWithQrcode(ctx)
  },
} satisfies Theme

---

License

MIT