@antdv-next/docs-plugins 0.0.1

package/src/plugins/demo.ts

@@ -0,0 +1,282 @@
+import type { MarkdownItEnv, MarkdownItHeader } from '@mdit-vue/types'
+import type MarkdownIt from 'markdown-it'
+import pathe from 'pathe'
+import { getDemoId } from '../demo/get-demo-id'
+
+const HEADING_LEVEL_RE = /^h([2-6])$/
+const SRC_ATTR_RE = /(\s|^)src=(['"])(.*?)\2/gi
+
+export interface DemoMarkdownPluginOptions {
+  /** 包裹 demo 的标签名，默认 `demo` */
+  wrapper?: string
+  /**
+   * demo 锚点归属模式：
+   * - `examples`：demo 统一挂到 slug 为 `examples` 的标题下（antdv-next 约定，默认）
+   * - `section`：demo 挂到当前所在章节标题下（跟随标题层级）
+   */
+  headerMode?: 'examples' | 'section'
+  /**
+   * 生产构建时跳过 `debug` demo 的目录收集
+   * @default true
+   */
+  debugDemo?: boolean
+}
+
+declare module '@mdit-vue/types' {
+  interface MarkdownItEnv {
+    id?: string
+  }
+}
+
+function checkWrapper(content: string, wrapper = 'demo') {
+  return new RegExp(`<${wrapper}(\\s|>|/)`, 'i').test(content)
+}
+
+function isProdDebugDemo(tag: string) {
+  if (process.env.NODE_ENV !== 'production') {
+    return false
+  }
+
+  const debugAttr = tag.match(/(?:^|\s)debug(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s/>]+)))?/i)
+  if (!debugAttr) {
+    return false
+  }
+
+  const value = debugAttr[1] ?? debugAttr[2] ?? debugAttr[3]
+  return value === undefined || value === '' || value === 'true'
+}
+
+function flattenHeaders(headers: MarkdownItHeader[] = []) {
+  const headerMap = new Map<string, MarkdownItHeader>()
+
+  const visit = (items: MarkdownItHeader[]) => {
+    for (const item of items) {
+      headerMap.set(item.slug, item)
+      if (item.children?.length)
+        visit(item.children)
+    }
+  }
+
+  visit(headers)
+  return headerMap
+}
+
+function flattenHeadersInOrder(headers: MarkdownItHeader[] = []) {
+  const flat: MarkdownItHeader[] = []
+
+  const visit = (items: MarkdownItHeader[]) => {
+    for (const item of items) {
+      flat.push(item)
+      if (item.children?.length)
+        visit(item.children)
+    }
+  }
+
+  visit(headers)
+  return flat
+}
+
+function getHeadingSlug(token: { attrs?: [string, string][] | null }) {
+  return token.attrs?.find(attr => attr[0] === 'id')?.[1]
+}
+
+function getHeadingTitle(token?: { type?: string, content?: string }) {
+  if (token?.type !== 'inline')
+    return ''
+  return token.content?.trim() ?? ''
+}
+
+function getHeadingLevel(token: { tag?: string }) {
+  const match = token.tag?.match(HEADING_LEVEL_RE)
+  if (!match)
+    return null
+  return Number(match[1])
+}
+
+export function replaceSrcPath(
+  content: string,
+  id: string,
+  root: string,
+  wrapper = 'demo',
+  parentHeader?: MarkdownItHeader,
+  skipDebugDemo = false,
+) {
+  function replaceSrcInTag(tagMatch: string, titleContent?: string) {
+    return tagMatch.replace(SRC_ATTR_RE, (srcMatch, prefix, quote, srcValue) => {
+      if (!srcValue || srcValue.startsWith('/'))
+        return srcMatch
+
+      const dir = pathe.dirname(id)
+      const filePath = pathe.resolve(dir, srcValue)
+      const relative = pathe.relative(root, filePath)
+
+      if (parentHeader && titleContent && !(skipDebugDemo && isProdDebugDemo(tagMatch))) {
+        const slug = getDemoId(filePath)
+        const item = {
+          level: parentHeader.level + 1,
+          title: titleContent,
+          slug,
+          link: `#${slug}`,
+          children: [],
+        }
+        if (parentHeader.children)
+          parentHeader.children.push(item)
+        else
+          parentHeader.children = [item]
+      }
+
+      return `${prefix}src=${quote}${relative.startsWith('/') ? relative : `/${relative}`}${quote}`
+    })
+  }
+
+  // 1. First, match closed tags <demo>Title</demo> to extract title content
+  const closedTag = new RegExp(`(<${wrapper}(?!-)\\b[^>]*>)([\\s\\S]*?)<\\/${wrapper}>`, 'gi')
+  let result = content.replace(closedTag, (tagMatch, openTag, titleContent) => {
+    return tagMatch.replace(
+      openTag,
+      replaceSrcInTag(openTag, titleContent?.trim()),
+    )
+  })
+
+  // 2. Then, match self-closing tags <demo ... />
+  const selfClosing = new RegExp(`<${wrapper}(?!-)\\b[^>]*/\\s*>`, 'gi')
+  result = result.replace(selfClosing, tagMatch => replaceSrcInTag(tagMatch))
+
+  // 3. Finally, match standalone open tags <demo ...> (when parsed separately from closing tag)
+  const openTag = new RegExp(`<${wrapper}(?!-)\\b[^>]*>`, 'gi')
+  return result.replace(openTag, tagMatch => replaceSrcInTag(tagMatch))
+}
+
+export function demoMarkdownPlugin(
+  md: MarkdownIt,
+  config: { root?: string } & DemoMarkdownPluginOptions = {},
+) {
+  const wrapper = config.wrapper ?? 'demo'
+  const headerMode = config.headerMode ?? 'examples'
+  const skipDebugDemo = config.debugDemo ?? true
+  // 保存原始 render 函数
+  const originalRender = md.renderer.render.bind(md.renderer)
+
+  md.renderer.render = function render(tokens, options, env: MarkdownItEnv) {
+    const root = config.root ?? process.cwd()
+    const currentId = env.id || ''
+    const headers = env.headers
+
+    // 'examples' 模式：所有 demo 统一挂到 slug 为 examples 的标题下
+    const fixedHeader = headerMode === 'examples'
+      ? headers?.find(item => item.slug === 'examples')
+      : undefined
+
+    const headerMap = flattenHeaders(headers)
+    const orderedHeaders = flattenHeadersInOrder(headers)
+    const headerIndexBySlug = new Map(
+      orderedHeaders.map((item, index) => [item.slug, index]),
+    )
+    const activeHeaders = new Map<number, MarkdownItHeader>()
+    let headerCursor = 0
+
+    function getCurrentHeader() {
+      const levels = Array.from(activeHeaders.keys()).sort(
+        (left, right) => right - left,
+      )
+      const nearestLevel = levels[0]
+      return nearestLevel ? activeHeaders.get(nearestLevel) : undefined
+    }
+
+    function resolveHeading(
+      headingLevel: number,
+      headingSlug?: string,
+      headingTitle?: string,
+    ) {
+      if (headingSlug) {
+        const bySlug = headerMap.get(headingSlug)
+        if (bySlug) {
+          const index = headerIndexBySlug.get(headingSlug)
+          if (typeof index === 'number')
+            headerCursor = Math.max(headerCursor, index + 1)
+          return bySlug
+        }
+      }
+
+      for (let index = headerCursor; index < orderedHeaders.length; index += 1) {
+        const header = orderedHeaders[index]!
+        if (header.level !== headingLevel)
+          continue
+        if (headingTitle && header.title !== headingTitle)
+          continue
+
+        headerCursor = index + 1
+        return header
+      }
+
+      return undefined
+    }
+
+    function processToken(token: {
+      type?: string
+      tag?: string
+      attrs?: [string, string][] | null
+      content?: string
+      children?: unknown[] | null
+    }) {
+      const tokenType = token.type ?? ''
+      const tokenContent = token.content ?? ''
+
+      if (
+        (tokenType === 'html_block'
+          || tokenType === 'html_inline'
+          || tokenType === 'inline')
+        && checkWrapper(tokenContent, wrapper)
+      ) {
+        token.content = replaceSrcPath(
+          tokenContent,
+          currentId,
+          root,
+          wrapper,
+          headerMode === 'examples' ? fixedHeader : getCurrentHeader(),
+          skipDebugDemo,
+        )
+      }
+
+      if (token.children) {
+        for (const child of token.children as (typeof token)[]) {
+          processToken(child)
+        }
+      }
+    }
+
+    const typedTokens = tokens as typeof tokens & Array<{
+      type: string
+      tag?: string
+      attrs?: [string, string][] | null
+      content?: string
+      children?: unknown[] | null
+    }>
+
+    typedTokens.forEach((token, index) => {
+      if (token.type === 'heading_open') {
+        const headingLevel = getHeadingLevel(token)
+        if (headingLevel) {
+          for (const level of activeHeaders.keys()) {
+            if (level >= headingLevel)
+              activeHeaders.delete(level)
+          }
+
+          const headingSlug = getHeadingSlug(token)
+          const headingTitle = getHeadingTitle(typedTokens[index + 1])
+          const header = resolveHeading(
+            headingLevel,
+            headingSlug,
+            headingTitle,
+          )
+          if (header)
+            activeHeaders.set(headingLevel, header)
+        }
+      }
+
+      processToken(token)
+    })
+
+    return originalRender(tokens, options, env)
+  }
+}

package/src/plugins/github-alerts.ts

@@ -0,0 +1,69 @@
+import type MarkdownIt from 'markdown-it'
+import type { ContainerOptions } from './container'
+
+const markerRE
+  = /^\[!(TIP|NOTE|INFO|IMPORTANT|WARNING|CAUTION|DANGER)\]([^\n\r]*)/i
+
+export function gitHubAlertsPlugin(md: MarkdownIt, options?: ContainerOptions) {
+  const titleMark = {
+    tip: options?.tipLabel || 'TIP',
+    note: options?.noteLabel || 'NOTE',
+    info: options?.infoLabel || 'INFO',
+    important: options?.importantLabel || 'IMPORTANT',
+    warning: options?.warningLabel || 'WARNING',
+    caution: options?.cautionLabel || 'CAUTION',
+    danger: options?.dangerLabel || 'DANGER',
+  } as Record<string, string>
+
+  md.core.ruler.after('block', 'github-alerts', (state) => {
+    const tokens = state.tokens
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i]!.type !== 'blockquote_open')
+        continue
+
+      const startIndex = i
+      const open = tokens[startIndex]!
+      let endIndex = i + 1
+      while (
+        endIndex < tokens.length
+        && (tokens[endIndex]!.type !== 'blockquote_close'
+          || tokens[endIndex]!.level !== open.level)
+      ) {
+        endIndex++
+      }
+      if (endIndex === tokens.length)
+        continue
+      const close = tokens[endIndex]!
+      const firstContent = tokens
+        .slice(startIndex, endIndex + 1)
+        .find(token => token.type === 'inline')
+      if (!firstContent)
+        continue
+      const match = firstContent.content.match(markerRE)
+      if (!match)
+        continue
+      const type = match[1]!.toLowerCase()
+      const title = match[2]?.trim() || titleMark[type] || capitalize(type)
+      firstContent.content = firstContent.content
+        .slice(match[0].length)
+        .trimStart()
+      open.type = 'github_alert_open'
+      open.tag = 'div'
+      open.meta = {
+        title,
+        type,
+      }
+      close.type = 'github_alert_close'
+      close.tag = 'div'
+    }
+  })
+  md.renderer.rules.github_alert_open = function (tokens, idx) {
+    const { title, type } = tokens[idx]!.meta
+    const attrs = ''
+    return `<div class="${type} custom-block github-alert"${attrs}><p class="custom-block-title">${title}</p>\n`
+  }
+}
+
+function capitalize(str: string) {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}

package/src/plugins/image.ts

@@ -0,0 +1,29 @@
+// markdown-it plugin for normalizing image source
+
+import type MarkdownIt from 'markdown-it'
+import { EXTERNAL_URL_RE } from '../shared'
+
+export interface ImagePluginOptions {
+  /**
+   * Support native lazy loading for the `<img>` tag.
+   * @default false
+   */
+  lazyLoading?: boolean
+}
+
+export function imagePlugin(md: MarkdownIt, { lazyLoading }: ImagePluginOptions = {}) {
+  const imageRule = md.renderer.rules.image!
+  md.renderer.rules.image = (tokens, idx, options, env, self) => {
+    const token = tokens[idx]!
+    let url = token.attrGet('src')
+    if (url && !EXTERNAL_URL_RE.test(url)) {
+      if (!/^\.?\//.test(url))
+        url = `./${url}`
+      token.attrSet('src', decodeURIComponent(url))
+    }
+    if (lazyLoading)
+      token.attrSet('loading', 'lazy')
+
+    return imageRule(tokens, idx, options, env, self)
+  }
+}

package/src/plugins/link.ts

@@ -0,0 +1,32 @@
+import type MarkdownIt from 'markdown-it'
+import { EXTERNAL_URL_RE } from '../shared'
+
+/**
+ * 让 markdown 中的外部链接在新标签页打开。
+ *
+ * 仅对带协议（http(s)://、mailto: 等）的外部链接生效，
+ * 站内相对链接保持默认行为，避免影响路由内跳转与锚点导航。
+ *
+ * 已通过 `markdown-it-attrs` 等方式显式声明的 `target` / `rel`
+ * 不会被覆盖，保留作者对单个链接的控制权。
+ */
+export function linkPlugin(md: MarkdownIt) {
+  const defaultLinkRender
+    = md.renderer.rules.link_open
+      || ((tokens, idx, options, _env, self) =>
+        self.renderToken(tokens, idx, options))
+
+  md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
+    const token = tokens[idx]!
+    const href = token.attrGet('href')
+
+    if (href && EXTERNAL_URL_RE.test(href)) {
+      if (!token.attrGet('target'))
+        token.attrSet('target', '_blank')
+      if (!token.attrGet('rel'))
+        token.attrSet('rel', 'noopener noreferrer')
+    }
+
+    return defaultLinkRender(tokens, idx, options, env, self)
+  }
+}

package/src/plugins/pre-wrapper.ts

@@ -0,0 +1,49 @@
+import type MarkdownIt from 'markdown-it'
+
+export interface Options {
+  hasSingleTheme: boolean
+}
+
+export function preWrapperPlugin(md: MarkdownIt, options: Options) {
+  const fence = md.renderer.rules.fence!
+  md.renderer.rules.fence = (...args) => {
+    const [tokens, idx] = args
+    const token = tokens[idx]!
+
+    // remove title from info
+    token.info = token.info.replace(/\[.*\]/, '')
+
+    const active = / active(?: |$)/.test(token.info) ? ' active' : ''
+    token.info = token.info.replace(/ active$/, '').replace(/ active /, ' ')
+
+    const lang = extractLang(token.info)
+    const rawCode = fence(...args)
+    return `<div class="language-${lang}${getAdaptiveThemeMarker(
+      options,
+    )}${active}"><button title="Copy Code" class="copy"></button><span class="lang">${lang}</span>${rawCode}</div>`
+  }
+}
+
+export function getAdaptiveThemeMarker(options: Options) {
+  return options.hasSingleTheme ? '' : ' ant-code-theme'
+}
+
+export function extractTitle(info: string, html = false) {
+  if (html) {
+    return (
+      info.replace(/<!--[\s\S]*?-->/g, '').match(/data-title="(.*?)"/)?.[1] || ''
+    )
+  }
+  return info.match(/\[(.*)\]/)?.[1] || extractLang(info) || 'txt'
+}
+
+function extractLang(info: string) {
+  return info
+    .trim()
+    .replace(/=(\d*)/, '')
+  // eslint-disable-next-line regexp/optimal-quantifier-concatenation
+    .replace(/:(no-)?line-numbers(\{| |$|=\d*).*/, '')
+    .replace(/(-vue|\{| ).*$/, '')
+    .replace(/^vue-html$/, 'template')
+    .replace(/^ansi$/, '')
+}

package/src/plugins/stackblitz.ts

@@ -0,0 +1,32 @@
+import type MarkdownIt from 'markdown-it'
+
+export function stackblitzPlugin(md: MarkdownIt) {
+  const fence = md.renderer.rules.fence!
+  md.renderer.rules.fence = (...args) => {
+    const [tokens, idx] = args
+    const token = tokens[idx]!
+    const info = token.info.trim()
+
+    if (info.startsWith('stackblitz')) {
+      const code = token.content
+      // Extract title from {title="..."}
+      const titleMatch = info.match(/\{[^}]*title\s*=\s*"([^"]*)"[^}]*\}/)
+      const title = titleMatch ? titleMatch[1]! : ''
+
+      // Encode the code for safe HTML attribute usage
+      const encodedCode = encodeURIComponent(code)
+
+      return `<stackblitz code="${encodedCode}" title="${escapeHtml(title)}"></stackblitz>`
+    }
+
+    return fence(...args)
+  }
+}
+
+function escapeHtml(str: string) {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}

package/src/plugins/table.ts

@@ -0,0 +1,39 @@
+import type MarkdownIt from 'markdown-it'
+import type StateCore from 'markdown-it/lib/rules_core/state_core.mjs'
+
+export function tablePlugin(md: MarkdownIt) {
+  md.core.ruler.push('table_api_attribute', (state: StateCore) => {
+    const tokens = state.tokens
+    let inApiSection = false
+
+    for (let i = 0; i < tokens.length; i++) {
+      const token = tokens[i]!
+
+      // 检测 ## 标题
+      if (token.type === 'heading_open' && token.tag === 'h2') {
+        // 获取标题内容（下一个 token 是 inline）
+        const inlineToken = tokens[i + 1]
+        if (inlineToken && inlineToken.type === 'inline') {
+          const headingText = inlineToken.content.trim().toLowerCase()
+          // 检查是否是 Api 标题（支持 Api、API、api 等）
+          if (headingText === 'api') {
+            inApiSection = true
+          }
+          else {
+            // 遇到其他 ## 标题，结束 Api 区域
+            inApiSection = false
+          }
+        }
+      }
+
+      // 如果在 Api 区域内，给 table 添加类名
+      if (inApiSection && token.type === 'table_open') {
+        const existingClass = token.attrGet('class') || ''
+        const newClass = existingClass ? `${existingClass} component-table-api` : 'component-table-api'
+        token.attrSet('class', newClass)
+      }
+    }
+
+    return true
+  })
+}

package/src/shared.ts

@@ -0,0 +1,4 @@
+export const EXTERNAL_URL_RE = /^(?:[a-z]+:|\/\/)/i
+export const SCRIPT_REGEX = /<script\b[^>]*>[\s\S]*?<\/script>/gi
+export const STYLE_REGEX = /<style\b[^>]*>[\s\S]*?<\/style>/gi
+export const DOCS_REGEX = /<docs\b[^>]*>[\s\S]*?<\/docs>/gi

package/src/utils/short-hash.ts

@@ -0,0 +1,27 @@
+const BASE62 = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+function toBase62(num: number): string {
+  let str = ''
+  do {
+    str = BASE62[num % 62] + str
+    num = Math.floor(num / 62)
+  } while (num > 0)
+  return str
+}
+
+export function shortHash(str: string): string {
+  const encoder = new TextEncoder()
+  const bytes = encoder.encode(str)
+
+  let hash = 2166136261
+  for (let i = 0; i < bytes.length; i++) {
+    hash ^= bytes[i]!
+    hash += (hash << 1)
+      + (hash << 4)
+      + (hash << 7)
+      + (hash << 8)
+      + (hash << 24)
+  }
+
+  return toBase62(hash >>> 0) // 无符号整数 → Base62
+}