feat: support version badges in markdown tables and sidebar (#269)

Author: SonyLeo

docs/.vitepress/config.mts

@@ -3,6 +3,7 @@ import vueJsx from '@vitejs/plugin-vue-jsx'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vitepress'
 import { vitepressDemoPlugin } from 'vitepress-demo-plugin'
+import { SidebarBadgePlugin, MarkdownBadgePlugin } from './plugins/badge'
 
 const { version } = pkg
 
@@ -77,7 +78,7 @@ export default defineConfig({
     ],
   ],
   vite: {
-    plugins: [vueJsx()],
+    plugins: [vueJsx(), SidebarBadgePlugin()],
     server: {
       open: true,
       proxy: process.env.VP_MODE === 'development' ? { '/playground': 'http://localhost:5184' } : undefined,
@@ -99,6 +100,8 @@ export default defineConfig({
           return code.replace(/import\.meta\.env\.BASE_URL/g, `'${process.env.VITEPRESS_BASE || '/'}'`)
         },
       })
+      // 添加 Markdown 内容中的版本标记支持
+      md.use(MarkdownBadgePlugin)
     },
   },
   themeConfig: {

docs/.vitepress/plugins/badge/MarkdownPlugin.ts

@@ -0,0 +1,53 @@
+/* eslint-disable */
+/**
+ * Markdown Badge 插件
+ *
+ * 功能：在 markdown 内容中支持 @new、@deprecated、@1.2.0 等版本标记语法
+ *
+ * @example
+ * ```markdown
+ * | 属性名 | 说明 | 类型 |
+ * | ------ | ---- | ---- |
+ * | count @new | 数量 | number |
+ * | oldProp @deprecated | 旧属性 | string |
+ * | version @1.2.0 | 版本 | string |
+ * ```
+ *
+ * @example
+ * ```ts
+ * // config.mts
+ * import { MarkdownBadgePlugin } from './plugins/badge'
+ *
+ * export default defineConfig({
+ *   markdown: {
+ *     config: (md) => {
+ *       md.use(MarkdownBadgePlugin)
+ *     }
+ *   }
+ * })
+ * ```
+ */
+
+import { MARKDOWN_BADGE_REGEX } from './constants'
+import { createBadgeHTML } from './utils'
+
+export function MarkdownBadgePlugin(md: any): void {
+  const defaultRender = md.renderer.rules.text
+
+  md.renderer.rules.text = (tokens: any, idx: any, options: any, env: any, self: any) => {
+    const token = tokens[idx]
+    let content = token.content
+
+    // 检查是否包含版本标记
+    if (MARKDOWN_BADGE_REGEX.test(content)) {
+      MARKDOWN_BADGE_REGEX.lastIndex = 0
+      content = content.replace(MARKDOWN_BADGE_REGEX, (_: any, badge: any) => {
+        return createBadgeHTML(badge)
+      })
+
+      return content
+    }
+
+    return defaultRender ? defaultRender(tokens, idx, options, env, self) : content
+  }
+}

docs/.vitepress/plugins/badge/SidebarPlugin.ts

@@ -0,0 +1,162 @@
+/* eslint-disable */
+/**
+ * Sidebar Badge 插件
+ *
+ * 功能：从 markdown 文件的 frontmatter 中读取 badge，自动添加到 sidebar
+ *
+ * @example
+ * ```ts
+ * // config.mts
+ * import { SidebarBadgePlugin } from './plugins/badge'
+ *
+ * export default defineConfig({
+ *   vite: {
+ *     plugins: [SidebarBadgePlugin({ debug: true })]
+ *   }
+ * })
+ * ```
+ */
+
+import fs from 'fs'
+import path from 'path'
+import { withBadge } from './utils'
+
+export interface SidebarBadgeOptions {
+  /**
+   * 源文件目录，默认为 'src'
+   */
+  srcDir?: string
+  /**
+   * 是否启用调试日志
+   */
+  debug?: boolean
+}
+
+export function SidebarBadgePlugin(options?: SidebarBadgeOptions): any {
+  let vpConfig: any = null
+  const { srcDir = 'src', debug = false } = options || {}
+  let badgeCount = 0
+
+  return {
+    name: 'vitepress-sidebar-badge',
+
+    async configResolved(config: any) {
+      if (vpConfig) return
+
+      vpConfig = config.vitepress
+      if (!vpConfig) {
+        console.warn('[SidebarBadge] VitePress config not found')
+        return
+      }
+
+      try {
+        const { default: matter } = await import('gray-matter')
+
+        const sidebar = vpConfig.site.themeConfig.sidebar
+        if (!sidebar) {
+          console.warn('[SidebarBadge] No sidebar config found')
+          return
+        }
+
+        badgeCount = processSidebar(sidebar, vpConfig.root || process.cwd(), srcDir, matter, debug)
+
+        if (badgeCount > 0) {
+          console.log(`✅ SidebarBadge: ${badgeCount} badge(s) applied`)
+        } else if (debug) {
+          console.log('ℹ️ SidebarBadge: No badges found')
+        }
+      } catch (error) {
+        console.error('[SidebarBadge] Error:', error)
+      }
+    },
+  }
+}
+
+/**
+ * 处理 sidebar 配置
+ */
+function processSidebar(sidebar: any, rootDir: string, srcDir: string, matter: any, debug: boolean): number {
+  let count = 0
+  const processedItems = new Set<any>()
+
+  if (Array.isArray(sidebar)) {
+    count = processSidebarArray(sidebar, rootDir, srcDir, matter, debug, processedItems)
+  } else if (typeof sidebar === 'object') {
+    Object.keys(sidebar).forEach((key) => {
+      const sidebarConfig = sidebar[key]
+      if (Array.isArray(sidebarConfig)) {
+        const dirName = key.replace(/^\//, '').replace(/\/$/, '')
+        count += processSidebarArray(sidebarConfig, rootDir, srcDir, matter, debug, processedItems, dirName)
+      }
+    })
+  }
+
+  return count
+}
+
+/**
+ * 处理 sidebar 数组
+ */
+function processSidebarArray(
+  sidebarArray: any[],
+  rootDir: string,
+  srcDir: string,
+  matter: any,
+  debug: boolean,
+  processedItems: Set<any>,
+  dirName?: string,
+): number {
+  let count = 0
+
+  sidebarArray.forEach((group) => {
+    if (group.items && Array.isArray(group.items)) {
+      const baseDir = group.base ? group.base.replace(/^\//, '').replace(/\/$/, '') : dirName
+
+      group.items.forEach((item: any) => {
+        if (item.link) {
+          const badge = readBadgeFromFrontmatter(item.link, rootDir, srcDir, baseDir || '', matter, debug)
+          if (badge && !processedItems.has(item)) {
+            item.text = withBadge(item.text, badge)
+            processedItems.add(item)
+            count++
+            if (debug) {
+              console.log(`[SidebarBadge] ✓ ${item.link}: ${badge}`)
+            }
+          }
+        }
+      })
+    }
+  })
+
+  return count
+}
+
+/**
+ * 从 markdown frontmatter 读取 badge
+ */
+function readBadgeFromFrontmatter(
+  link: string,
+  rootDir: string,
+  srcDir: string,
+  baseDir: string,
+  matter: any,
+  debug: boolean,
+): string | undefined {
+  try {
+    const filePath = path.join(rootDir, srcDir, baseDir, `${link}.md`)
+
+    if (!fs.existsSync(filePath)) {
+      return undefined
+    }
+
+    const content = fs.readFileSync(filePath, 'utf-8')
+    const { data } = matter(content)
+
+    return data.badge as string | undefined
+  } catch (error) {
+    if (debug) {
+      console.warn(`[SidebarBadge] ✗ ${link}: ${error}`)
+    }
+    return undefined
+  }
+}

docs/.vitepress/plugins/badge/constants.ts

@@ -0,0 +1,48 @@
+/**
+ * Badge 相关常量配置
+ */
+
+/**
+ * Badge 类型定义
+ */
+export type BadgeType = 'new' | 'deprecated' | 'beta' | 'alpha'
+
+/**
+ * Badge 值类型（包含固定类型和版本号字符串）
+ */
+export type BadgeValue = BadgeType | string
+
+/**
+ * Badge 类型到中文文本的映射
+ */
+export const BADGE_TEXT_MAP: Record<BadgeType, string> = {
+  new: '新增',
+  deprecated: '已废弃',
+  beta: 'Beta',
+  alpha: 'Alpha',
+}
+
+/**
+ * Badge CSS 类名映射
+ */
+export const BADGE_CLASS_MAP: Record<BadgeType, string> = {
+  new: 'version-badge version-badge--new',
+  deprecated: 'version-badge version-badge--deprecated',
+  beta: 'version-badge version-badge--beta',
+  alpha: 'version-badge version-badge--alpha',
+}
+
+/**
+ * 版本号正则表达式（支持 v0.4.0 或 0.4.0 格式）
+ * 格式：\d+ - 至少一个数字开头
+ *       (?:\.\d+)* - 零或多个 .数字 组合
+ *       (?:[-+][a-zA-Z0-9.]+)? - 可选的预发布版本或构建元数据
+ * 有效：1, 1.2, 1.2.3, v1.2.3-beta.1
+ * 无效：..., 1.., .1., 1.
+ */
+export const VERSION_NUMBER_REGEX = /^v?\d+(?:\.\d+)*(?:[-+][a-zA-Z0-9.]+)?$/
+
+/**
+ * Markdown 中的版本标记正则表达式（用于 @new、@1.2.0 等）
+ */
+export const MARKDOWN_BADGE_REGEX = /@(new|deprecated|beta|alpha|\d+(?:\.\d+)*(?:[-+][a-zA-Z0-9.]+)?)/g

docs/.vitepress/plugins/badge/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Badge 插件统一导出
+ */
+
+export { SidebarBadgePlugin } from './SidebarPlugin'
+export { MarkdownBadgePlugin } from './MarkdownPlugin'
+export * from './constants'
+export * from './utils'
+
+export type { SidebarBadgeOptions } from './SidebarPlugin'

docs/.vitepress/plugins/badge/utils.ts

@@ -0,0 +1,69 @@
+/**
+ * Badge 工具函数
+ */
+
+import type { BadgeType, BadgeValue } from './constants'
+import { BADGE_TEXT_MAP, BADGE_CLASS_MAP, VERSION_NUMBER_REGEX } from './constants'
+
+/**
+ * 转义 HTML 特殊字符以防止 XSS
+ */
+function escapeHtml(text: string): string {
+  const htmlEscapeMap: Record<string, string> = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+  }
+  return text.replace(/[&<>"']/g, (char) => htmlEscapeMap[char])
+}
+
+/**
+ * 判断是否为版本号
+ */
+export function isVersionNumber(badge: string): boolean {
+  return VERSION_NUMBER_REGEX.test(badge)
+}
+
+/**
+ * 获取 Badge 类型
+ */
+export function getBadgeType(badge: BadgeValue): BadgeType {
+  return isVersionNumber(badge) ? 'new' : (badge as BadgeType)
+}
+
+/**
+ * 获取 Badge 显示文本
+ */
+export function getBadgeText(badge: BadgeValue): string {
+  if (isVersionNumber(badge)) {
+    return badge
+  }
+  return BADGE_TEXT_MAP[badge as BadgeType] || badge
+}
+
+/**
+ * 获取 Badge CSS 类名
+ */
+export function getBadgeClass(badge: BadgeValue): string {
+  const badgeType = getBadgeType(badge)
+  return BADGE_CLASS_MAP[badgeType] || BADGE_CLASS_MAP.new
+}
+
+/**
+ * 创建 Badge HTML
+ */
+export function createBadgeHTML(badge: BadgeValue): string {
+  const badgeText = escapeHtml(getBadgeText(badge))
+  const badgeClass = getBadgeClass(badge)
+  return `<span class="${badgeClass}">${badgeText}</span>`
+}
+
+/**
+ * 为文本添加 Badge
+ */
+export function withBadge(text: string, badge: BadgeValue): string {
+  const badgeHTML = createBadgeHTML(badge)
+  return `${text} ${badgeHTML}`
+}