Toolkit API

vitepress-plugin-toolkit is a VitePress plugin development toolkit that provides a rich set of utility functions to assist plugin development.

Installation:

pnpm

pnpm add vitepress-plugin-toolkit

npm

npm install vitepress-plugin-toolkit

bun

bun add vitepress-plugin-toolkit

deno

deno add vitepress-plugin-toolkit

yarn

yarn add vitepress-plugin-toolkit

Node-side API

Import from vitepress-plugin-toolkit:

import {
  createContainerPlugin,
  createContainerSyntaxPlugin,
  createEmbedRuleBlock,
  resolveAttrs,
  resolveAttr,
  stringifyAttrs,
  createLogger,
  createLocales,
  getVitepressConfig,
  getLocaleWithPath,
  resolveRouteLink,
  parseRect,
  slugify,
  treatAsHtml,
} from 'vitepress-plugin-toolkit'

---

createContainerPlugin

Create a markdown-it custom container plugin. Used for processing ::: type syntax, where content is parsed normally by markdown-it.

function createContainerPlugin(
  md: MarkdownIt,
  type: string,
  options?: ContainerOptions,
): void

ContainerOptions:

interface ContainerOptions {
  /**
   * Callback for rendering container opening tag
   */
  before?: (info: string, tokens: Token[], index: number, options: Options, env: any) => string
  /**
   * Callback for rendering container closing tag
   */
  after?: (info: string, tokens: Token[], index: number, options: Options, env: any) => string
}

Usage Example:

import { createContainerPlugin } from 'vitepress-plugin-toolkit'

function myPlugin(md) {
  createContainerPlugin(md, 'steps', {
    before: () => '<div class="vp-steps">',
  })
}

---

createContainerSyntaxPlugin

Create a custom syntax container plugin. Unlike createContainerPlugin, the content is not parsed by markdown-it and must be handled manually.

function createContainerSyntaxPlugin(
  md: MarkdownIt,
  type: string,
  render?: RenderRule,
): void

Raw content inside the container is accessible via token.content, and metadata via token.meta.

Usage Example:

import { createContainerSyntaxPlugin } from 'vitepress-plugin-toolkit'

function myPlugin(md) {
  createContainerSyntaxPlugin(md, 'file-tree', (tokens, index) => {
    const { content, meta } = tokens[index]
    return `<div class="file-tree">${content}</div>`
  })
}

---

createEmbedRuleBlock

Create an embed rule block for handling @[type ...](args) syntax.

function createEmbedRuleBlock<Meta extends Record<string, any>>(
  md: MarkdownIt,
  options: EmbedRuleBlockOptions<Meta>,
): void

EmbedRuleBlockOptions:

interface EmbedRuleBlockOptions<Meta extends Record<string, any>> {
  /** Embed type, e.g. 'pdf', 'qrcode' */
  type: string
  /** Token name, defaults to type */
  name?: string
  /** Name of the rule to insert before, default 'code' */
  beforeName?: string
  /** Syntax pattern regex */
  syntaxPattern: RegExp
  /** Rule options */
  ruleOptions?: RuleOptions
  /** Extract metadata from match */
  meta: (match: RegExpMatchArray) => Meta
  /** Generate content from metadata */
  content: (meta: Meta, content: string, env: MarkdownEnv) => string
}

Usage Example:

import { createEmbedRuleBlock } from 'vitepress-plugin-toolkit'

function myPlugin(md) {
  createEmbedRuleBlock(md, {
    type: 'pdf',
    syntaxPattern: /^@\[pdf([^\]]*)\]\(([^)]*)\)/,
    meta: (match) => ({
      attrs: match[1] || '',
      src: match[2] || '',
    }),
    content: (meta) => {
      return `<VPPdf src="${meta.src}" ${meta.attrs} />`
    },
  })
}

---

resolveAttrs

Parse an attribute string into an object.

function resolveAttrs<T extends Record<string, any> = Record<string, any>>(info: string): T

Example:

resolveAttrs('width="100%" height="400" dark')
// => { width: '100%', height: '400', dark: true }

---

resolveAttr

Parse a single attribute value from an info string.

function resolveAttr(info: string, key: string): string | undefined

---

stringifyAttrs

Serialize an attributes object into an HTML attribute string.

function stringifyAttrs<T extends object = object>(
  attrs: T,
  withUndefinedOrNull?: boolean,
  forceStringify?: (keyof T)[],
): string

Example:

stringifyAttrs({ width: '100%', height: 400, dark: true })
// => ' width="100%" :height="400" dark'

---

createLogger

Create a logger instance.

function createLogger(
  prefix: string,
  defaultLevel?: LogLevel,
): Logger

LogLevel:

type LogLevel = 'info' | 'warn' | 'error' | 'debug' | 'silent'

Example:

const logger = createLogger('my-plugin', 'info')

logger.info('Plugin loaded')       // [my-plugin] Plugin loaded
logger.warn('Potential issue')     // [my-plugin] Potential issue
logger.error('An error occurred')  // [my-plugin] An error occurred
logger.debug('Debug info', true)   // [my-plugin] Debug info

---

createLocales

Create multi-language configuration, automatically matching VitePress's language settings.

function createLocales<LocaleData extends Record<string, unknown>>(
  builtinLocales: BuiltinLocales<LocaleData>,
  userLocales?: Record<string, LocaleData>,
): Record<string, LocaleData>

Example:

const locales = createLocales(
  [
    [['en', 'en-US'], { chart: 'Chart', source: 'Source' }],
    [['zh', 'zh-CN'], { chart: '图表', source: '源码' }],
  ],
  userLocales,
)

---

getVitepressConfig

Get the current VitePress site configuration.

function getVitepressConfig(): SiteConfig

---

getLocaleWithPath

Get language information based on a file path.

function getLocaleWithPath(path: string): { lang: string, locale: string }

---

resolveRouteLink

Convert a relative path to a VitePress route link.

function resolveRouteLink(url: string, env: MarkdownEnv): string

---

parseRect

Parse a size string, automatically appending a unit if a number is passed.

function parseRect(str: string, unit?: string): string

Example:

parseRect('400')     // => '400px'
parseRect('50%')     // => '50%'
parseRect('10', 'rem') // => '10rem'

---

slugify

Convert a string to a URL-friendly slug format.

function slugify(str: string): string

---

treatAsHtml

Determine whether a filename should be treated as HTML (non-known-resource extensions are treated as HTML).

function treatAsHtml(filename: string): boolean

---

Client-side API

Import from vitepress-plugin-toolkit/client:

import {
  VPCopyButton,
  VPLoading,
  useSize,
  isiPhone,
  isWindows,
  isiPad,
  isIOS,
  isMacOS,
  isMobile,
  isSafari,
} from 'vitepress-plugin-toolkit/client'

VPCopyButton

Copy button component.

<template>
  <VPCopyButton :text="code" />
</template>

VPLoading

Loading state component.

<template>
  <VPLoading />
</template>

useSize

Responsive size calculation composable.

function useSize<T extends HTMLElement>(
  el: TemplateRef<T>,
  options: ToRefs<SizeOptions>,
  extraHeight?: MaybeRef<number>,
): {
  width: Ref<string>
  height: Ref<string>
  resize: () => void
}

SizeOptions:

interface SizeOptions {
  width?: string
  height?: string
  ratio?: number | string
}

Device Detection Utilities

Function	Description
isIPhone()	Check if iPhone
isIPad()	Check if iPad
isIOS()	Check if iOS device
isMacOS()	Check if macOS
isWindows()	Check if Windows
isMobile()	Check if mobile device
isSafari()	Check if Safari browser

---

Shared Utilities

Can be imported from either vitepress-plugin-toolkit or vitepress-plugin-toolkit/client:

import { isExternal, isLinkWithProtocol } from 'vitepress-plugin-toolkit'

isExternal

Check if a link is an external link.

function isExternal(path: string): boolean

isLinkWithProtocol

Check if a link contains a protocol prefix.

function isLinkWithProtocol(link: string): boolean

---

CSS Transition Animations

vitepress-plugin-toolkit provides predefined CSS transition animations that can be imported in plugins:

@import 'vitepress-plugin-toolkit/styles/transition/fade-in.css';
@import 'vitepress-plugin-toolkit/styles/transition/fade-in-up.css';
@import 'vitepress-plugin-toolkit/styles/transition/fade-in-down.css';
@import 'vitepress-plugin-toolkit/styles/transition/fade-in-left.css';
@import 'vitepress-plugin-toolkit/styles/transition/fade-in-right.css';
@import 'vitepress-plugin-toolkit/styles/transition/slide-in-up.css';
@import 'vitepress-plugin-toolkit/styles/transition/slide-in-down.css';
@import 'vitepress-plugin-toolkit/styles/transition/slide-in-left.css';
@import 'vitepress-plugin-toolkit/styles/transition/slide-in-right.css';
@import 'vitepress-plugin-toolkit/styles/transition/fade-in-scale-up.css';
@import 'vitepress-plugin-toolkit/styles/transition/fade-in-width-expand.css';
@import 'vitepress-plugin-toolkit/styles/transition/fade-in-height-expand.css';