@roidmc/vitepress-uni-icons

一个现代化的 VitePress 图标插件,为代码组和代码块添加文件图标。

特性

• 🚀 高性能 - 智能缓存和增量更新
• 🎨 主题支持 - 自动适配明暗主题
• 🔧 高度可配置 - 支持自定义图标映射
• 📦 开箱即用 - 内置常用图标映射
• 🎯 精确匹配 - 智能图标匹配算法
• 🌐 Iconify支持 - 支持所有Iconify图标集和API
• 🔄 自动扫描 - 自动发现已安装的图标集

安装

pnpm add @roidmc/vitepress-uni-icons

快速开始

1. 配置 VitePress

// .vitepress/config.ts
import { defineConfig } from 'vitepress'
import { uniIconsPlugin, uniIconsMarkdownPlugin } from '@roidmc/vitepress-uni-icons'

export default defineConfig({
  vite: {
    plugins: [
      uniIconsPlugin() as any
    ],
  },
  markdown: {
    config: (md) => {
      uniIconsMarkdownPlugin(md)
    },
  },
})

2. 注入CSS

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import 'virtual:uni-icons.css'

export default {
  extends: DefaultTheme,
}

3. 在 Markdown 中使用

::: code-group

```ts [config.ts]
export default { }
```

```js [config.js]
export default { }
```

:::

高级配置

自定义图标

import { uniIconsPlugin, localIconLoader, publicIconLoader } from '@roidmc/vitepress-uni-icons'

uniIconsPlugin({
  customIcons: {
    // Iconify图标
    'my-framework': 'mdi:star',
    
    // 本地SVG文件
    'custom': localIconLoader(import.meta.url, './assets/custom.svg'),
    
    // Public目录
    'git': publicIconLoader('git.svg'),
    
    // 主题图标
    'pnpm': {
      light: 'vscode-icons:file-type-light-pnpm',
      dark: 'vscode-icons:file-type-pnpm'
    }
  }
} as any)

使用Iconify图标集

uniIconsPlugin({
  iconSets: [
    {
      name: 'mdi',
      // 直接导入图标集
      icons: require('@iconify-json/mdi').icons,
      scan: {
        // 扫描配置
        prefix: '',  // 图标名前缀
        suffix: '',  // 图标名后缀
        theme: false // 是否处理light/dark主题
      }
    },
    {
      name: 'carbon',
      // 从包自动加载
      scan: { prefix: '' }
    }
  ]
} as any)

使用Iconify API

uniIconsPlugin({
  customIcons: {
    // 无需安装包,直接使用API
    'home': 'mdi:home',
    'github': 'mdi:github'
  }
} as any)

自定义样式

uniIconsPlugin({
  style: {
    iconSize: '1.2em',           // 图标大小
    iconMarginRight: '0.6em',    // 图标右边距
    iconMarginBottom: '-0.2em',  // 图标底部偏移
    titleBarFontSize: '16px',    // 标题栏字体大小
    titleBarLineHeight: '52px',  // 标题栏行高
    titleBarPadding: '0 16px'    // 标题栏内边距
  }
} as any)

禁用内置图标

uniIconsPlugin({
  disableBuiltin: true,  // 只使用自定义图标
  customIcons: {
    'vue': 'mdi:vuejs'
  }
} as any)

配置选项

interface PluginOptions {
  // 图标集配置
  iconSets?: IconSetConfig[]
  
  // 自定义图标映射
  customIcons?: IconMap
  
  // CSS样式配置
  style?: {
    iconSize?: string
    iconMarginRight?: string
    iconMarginBottom?: string
    titleBarFontSize?: string
    titleBarLineHeight?: string
    titleBarPadding?: string
  }
  
  // 默认标签列表(预生成CSS)
  defaultLabels?: string[]
  
  // 调试模式
  debug?: boolean
  
  // 禁用内置图标
  disableBuiltin?: boolean
}

图标格式

支持以下格式:

1. Iconify图标: collection:icon-name
2. 主题图标: { light: string, dark: string }
3. SVG字符串: <svg>...</svg>
4. URL: https://example.com/icon.svg
5. Public路径: /icons/git.svg

内置图标

插件内置了以下图标映射:

• 包管理器: pnpm, npm, yarn, bun, deno
• 框架: vue, react, svelte, angular, next, nuxt, astro, vitepress
• 构建工具: vite, webpack, rollup, esbuild
• 配置文件: package.json, tsconfig.json, .env
• 文件扩展名: .ts, .js, .vue, .json

License

2026 © RoidMC Studios | MPL-2.0