@antdv-next/docs-plugins 0.0.1

package/src/demo/types.ts

@@ -0,0 +1,23 @@
+export interface DemoLocale {
+  html?: string
+  title?: string
+}
+
+export interface DemoExtraFile {
+  name: string
+  lang: string
+  code: string
+}
+
+export interface DemoSourceData {
+  source: string
+  jsSource: string
+  extraFiles: DemoExtraFile[]
+}
+
+export interface DemoModule {
+  component?: () => Promise<unknown>
+  locales?: Record<string, DemoLocale>
+  sourceVersion: number
+  loadSource: (signal?: AbortSignal) => Promise<DemoSourceData>
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export * from './demo/formatter'
+export * from './demo/get-demo-id'
+export * from './demo/index'
+export * from './demo/tsToJs'
+export * from './demo/types'
+export * from './isolate-styles'
+export * from './markdown'
+export * from './md2vue'
+export * from './md-plugin'
+export * from './plugins/container'
+export * from './plugins/demo'
+export * from './plugins/github-alerts'
+export * from './plugins/image'
+export * from './plugins/link'
+export * from './plugins/pre-wrapper'
+export * from './plugins/stackblitz'
+export * from './plugins/table'
+export * from './shared'
+export * from './utils/short-hash'

package/src/isolate-styles.ts

@@ -0,0 +1,47 @@
+import type { Plugin } from 'postcss'
+import selectorParser from 'postcss-selector-parser'
+
+interface Options {
+  includeFiles?: RegExp[]
+  ignoreFiles?: RegExp[]
+  prefix?: string
+}
+
+/**
+ * PostCSS 插件：为 markdown 样式添加隔离前缀，
+ * 避免文档站点样式污染组件演示区（`.vp-raw` 内不做隔离）。
+ */
+export function postcssIsolateStyles({
+  includeFiles = [/styles\/markdown\/index\.css/],
+  ignoreFiles,
+  prefix = ':not(:where(.vp-raw, .vp-raw *))',
+}: Options = {}): Plugin {
+  const prefixNodes = selectorParser().astSync(prefix).first.nodes
+
+  return /* prettier-ignore */ {
+    postcssPlugin: 'postcss-isolate-styles',
+    Once(root) {
+      const file = root.source?.input.file
+      if (file && includeFiles?.length && !includeFiles.some(re => re.test(file)))
+        return
+      if (file && ignoreFiles?.length && ignoreFiles.some(re => re.test(file)))
+        return
+
+      root.walkRules((rule) => {
+        if (!rule.selector || rule.selector.includes(prefix))
+          return
+        if (rule.parent?.type === 'atrule' && /\bkeyframes$/i.test(rule.parent.name))
+          return
+
+        rule.selector = selectorParser((selectors) => {
+          selectors.each((sel) => {
+            if (!sel.nodes.length)
+              return
+            const insertionIndex = (sel as any).nodes.findLastIndex((n: any) => n.type !== 'pseudo') + 1
+            sel.nodes.splice(insertionIndex, 0, ...prefixNodes.map(n => n.clone() as any))
+          })
+        }).processSync(rule.selector)
+      })
+    },
+  }
+}

package/src/markdown.ts

@@ -0,0 +1,188 @@
+import type { MarkdownItAsync } from 'markdown-it-async'
+import type { DemoMarkdownPluginOptions } from './plugins/demo'
+import { frontmatterPlugin } from '@mdit-vue/plugin-frontmatter'
+import { headersPlugin } from '@mdit-vue/plugin-headers'
+import { titlePlugin } from '@mdit-vue/plugin-title'
+import { tocPlugin } from '@mdit-vue/plugin-toc'
+import { slugify } from '@mdit-vue/shared'
+import { fromAsyncCodeToHtml } from '@shikijs/markdown-it/async'
+import {
+  transformerMetaHighlight,
+  transformerMetaWordHighlight,
+  transformerNotationDiff,
+  transformerNotationErrorLevel,
+  transformerNotationFocus,
+  transformerNotationHighlight,
+  transformerNotationWordHighlight,
+} from '@shikijs/transformers'
+import anchorPlugin from 'markdown-it-anchor'
+import MarkdownIt from 'markdown-it-async'
+import attrsPlugin from 'markdown-it-attrs'
+// @ts-expect-error markdown-it-emoji has no proper types for this entry
+import { full as emoji } from 'markdown-it-emoji'
+import { codeToHtml } from 'shiki'
+import { containerPlugin } from './plugins/container'
+import { demoMarkdownPlugin } from './plugins/demo'
+import { gitHubAlertsPlugin } from './plugins/github-alerts'
+import { imagePlugin } from './plugins/image'
+import { linkPlugin } from './plugins/link'
+import { preWrapperPlugin } from './plugins/pre-wrapper'
+import { stackblitzPlugin } from './plugins/stackblitz'
+import { tablePlugin } from './plugins/table'
+
+export interface CreateMarkdownOptions {
+  /**
+   * 是否加载插件
+   * @default true
+   */
+  withPlugin?: boolean
+  /**
+   * 自定义插件前的钩子
+   */
+  preConfig?: (md: MarkdownItAsync) => void
+  /**
+   * 自定义插件后的钩子
+   */
+  config?: (md: MarkdownItAsync) => void
+  /**
+   * 资源路径配置
+   */
+  root?: string
+  /**
+   * markdown-it 层 demo 插件选项
+   */
+  demo?: DemoMarkdownPluginOptions
+  /**
+   * 外部链接在新标签页打开
+   * @default true
+   */
+  externalLink?: boolean
+}
+
+export function loadShiki(md: MarkdownItAsync, cls: string = 'ant-doc-code') {
+  md.use(fromAsyncCodeToHtml(codeToHtml, {
+    themes: {
+      light: 'vitesse-light',
+      dark: 'vitesse-dark',
+    },
+    defaultColor: false,
+    cssVariablePrefix: '--ant-doc-',
+    transformers: [
+      transformerMetaHighlight(),
+      transformerMetaWordHighlight(),
+      transformerNotationDiff(),
+      transformerNotationErrorLevel(),
+      transformerNotationFocus(),
+      transformerNotationHighlight(),
+      transformerNotationWordHighlight(),
+      {
+        name: 'remove:clean-up',
+        code(element) {
+          if (element.tagName === 'code' && element.properties.class)
+            delete element.properties.class
+        },
+        pre(element) {
+          delete element.properties.tabindex
+          delete element.properties.style
+          this.addClassToHast(element, cls)
+        },
+      },
+    ],
+  }))
+}
+
+export function loadBaseMd(md: MarkdownItAsync, options: { externalLink?: boolean } = {}) {
+  // 允许在 markdown 中使用 frontmatter
+  md.use(frontmatterPlugin)
+  // 头部插件
+  md.use(headersPlugin, {
+    level: [2, 3, 4, 5, 6],
+    slugify,
+  })
+  // 标题插件
+  md.use(titlePlugin)
+  // 加载emoji表情包
+  md.use(emoji)
+  // 加载处理器
+  md.use(attrsPlugin)
+  // 外部链接新标签页打开
+  if (options.externalLink !== false)
+    md.use(linkPlugin)
+  // 加载容器插件
+  md.use(containerPlugin)
+  // 加载github警告插件
+  md.use(gitHubAlertsPlugin)
+}
+
+function withPlugins(md: MarkdownItAsync, options: CreateMarkdownOptions) {
+  // 处理demo
+  md.use(demoMarkdownPlugin, {
+    root: options.root,
+    ...options.demo,
+  })
+  // 加载基础markdown配置
+  loadBaseMd(md, options)
+  // 目录插件
+  md.use(tocPlugin)
+  // 加载anchor插件
+  md.use(anchorPlugin, {
+    slugify,
+    permalink: anchorPlugin.permalink.linkInsideHeader({
+      symbol: '​',
+      renderAttrs: (slug, state) => {
+        // Find `heading_open` with the id identical to slug
+        const idx = state.tokens.findIndex((token) => {
+          const attrs = token.attrs
+          const id = attrs?.find(attr => attr[0] === 'id')
+          return id && slug === id[1]
+        })
+        // Get the actual heading content
+        const title = state.tokens[idx + 1]?.content || ''
+        return {
+          'aria-label': `Permalink to "${title}"`,
+        }
+      },
+    }),
+  })
+  // 配置加载高亮配置
+  loadShiki(md)
+  // 加载图片插件
+  md.use(imagePlugin)
+  // 加载pre标签包裹插件
+  md.use(preWrapperPlugin, {
+    hasSingleTheme: false, // 是否只有一个主题
+  })
+  // 加载表格插件，为 Api 区域的表格添加属性
+  md.use(tablePlugin)
+  // 加载 StackBlitz 代码块插件
+  md.use(stackblitzPlugin)
+
+  // 禁用markdown自动识别链接
+  md.linkify.set({ fuzzyLink: false })
+}
+
+export function createMarkdown() {
+  let md: MarkdownItAsync | undefined
+  return (options: CreateMarkdownOptions = {}) => {
+    if (md) {
+      return md
+    }
+    md = MarkdownIt({
+      html: true,
+      linkify: true,
+      typographer: true,
+    })
+    if (options.preConfig) {
+      options.preConfig(md)
+    }
+    if (options.withPlugin !== false) {
+      withPlugins(md, options)
+    }
+    if (options.config) {
+      options.config(md)
+    }
+    return md
+  }
+}
+
+export const useMarkdown = createMarkdown()

package/src/md-plugin.ts

@@ -0,0 +1,24 @@
+import type { PluginOption } from 'vite'
+import type { DemoPluginOptions } from './demo/index'
+import type { CreateMarkdownOptions } from './markdown'
+import { demoPlugin } from './demo/index'
+import { md2VuePlugin } from './md2vue'
+
+export interface DocsPluginsOptions {
+  /**
+   * markdown-it 渲染链路选项（传给 md2vue / createMarkdown）
+   */
+  markdown?: CreateMarkdownOptions
+  /**
+   * vite demo 插件选项
+   */
+  demo?: DemoPluginOptions
+}
+
+/** docs 站点默认的 markdown 处理插件组合 */
+export function mdPlugin(options: DocsPluginsOptions = {}): PluginOption[] {
+  return [
+    md2VuePlugin(options.markdown),
+    demoPlugin(options.demo),
+  ]
+}

package/src/md2vue.ts

@@ -0,0 +1,163 @@
+import type { MarkdownItEnv } from '@mdit-vue/types'
+import type { PluginOption } from 'vite'
+import type { CreateMarkdownOptions } from './markdown'
+import { LRUCache } from 'lru-cache'
+import { findStaticImports } from 'mlly'
+import pathe from 'pathe'
+import { useMarkdown } from './markdown'
+import { SCRIPT_REGEX, STYLE_REGEX } from './shared'
+import { shortHash } from './utils/short-hash'
+
+export function formatPageData(env: MarkdownItEnv) {
+  const pageData = {
+    title: env.title ?? '',
+    frontmatter: env.frontmatter ?? {},
+    headers: env.headers ?? [],
+    description: '',
+  }
+
+  if (typeof env.frontmatter?.description === 'string')
+    pageData.description = env.frontmatter.description
+
+  if (typeof env.frontmatter?.title === 'string' && !env.title)
+    pageData.title = env.frontmatter.title
+
+  return pageData
+}
+
+export function checkPkgImport(findCode: string, pkg: string, importName: string) {
+  if (!findCode)
+    return false
+  const imports = findStaticImports(findCode)
+  return imports.some(
+    item => item.specifier === pkg && item.imports.includes(importName),
+  )
+}
+
+export function addScriptSetup(scriptTags: RegExpMatchArray | null, env: MarkdownItEnv) {
+  const pageData = formatPageData(env)
+  const baseCode = `const __pageData = ${JSON.stringify(pageData)};\nconst frontmatter = ${JSON.stringify(env.frontmatter ?? {})};\n`
+  const importsCode = `import { inject, provide, ref } from 'vue';\n`
+  const injectedCode = `const __parentPageData = ref({});provide('__pageData__',(data)=>{__parentPageData.value=data});const __pageDataFunc__ = inject('__pageData__',null);if(__pageDataFunc__)__pageDataFunc__(__pageData);provide('__pageInfo__',__pageData);defineExpose({frontmatter,pageData:__pageData})`
+
+  if (!scriptTags || !scriptTags.length) {
+    return `<script setup lang="ts">\n${importsCode}${baseCode}${injectedCode}\n</script>\n`
+  }
+  const scriptSetupCode = scriptTags.find((v) => {
+    // 只要是单行的script标签，中包含<script setup>的标签
+    return /<script\b[^>]+\bsetup\b[^>]*>/i.test(v)
+  })
+  if (!scriptSetupCode) {
+    // 如果没有找到script setup标签，则直接返回
+    return `<script setup lang="ts">\n${importsCode}${baseCode}${injectedCode}\n</script>\n${scriptTags.join('\n')}\n`
+  }
+  // 剩余的script代码
+  const restScriptTags = scriptTags.filter((v) => {
+    return v !== scriptSetupCode
+  })
+  // 获取内部的代码
+  const scriptContent = scriptSetupCode
+    ? scriptSetupCode
+        .replace(/<script\b[^>]+\bsetup\b[^>]*>/i, '')
+        .replace(/<\/script>/i, '')
+    : ''
+  const importArr: string[] = []
+  if (!checkPkgImport(scriptContent, 'vue', 'provide'))
+    importArr.push('provide')
+  if (!checkPkgImport(scriptContent, 'vue', 'inject'))
+    importArr.push('inject')
+  if (!checkPkgImport(scriptContent, 'vue', 'ref'))
+    importArr.push('ref')
+  const _importsCode = importArr.length
+    ? `import { ${importArr.join(', ')} } from 'vue';\n`
+    : ''
+  return `<script setup lang="ts">\n${_importsCode}${scriptContent}${baseCode}${injectedCode}\n</script>\n${restScriptTags.join('\n')}\n`
+}
+
+export function md2Vue(code: string, env: MarkdownItEnv) {
+  // 先处理代码块，转义其中可能影响 Vue 模板解析的特殊字符
+  code = code.replace(/<pre\b[^>]*>[\s\S]*?<\/pre>/gi, (match) => {
+    // 转义 { } 避免被 Vue 模板引擎误解析
+    return match
+      .replace(/\{/g, '&#123;')
+      .replace(/\}/g, '&#125;')
+  })
+
+  const scriptTags = code.match(SCRIPT_REGEX)
+  const styleTags = code.match(STYLE_REGEX)
+  // Remove script and style tags from the original code
+  const templateCode = code.replace(SCRIPT_REGEX, '').replace(STYLE_REGEX, '')
+  // Create a Vue component string
+  const vueComponent = `<template>\n<div class="ant-doc vp-doc">${templateCode}</div>\n</template>\n`
+  const scriptContent = addScriptSetup(scriptTags, env)
+  const styleContent = styleTags ? styleTags.join('\n') : ''
+  return `${scriptContent}\n${vueComponent}\n${styleContent}`
+}
+
+export function md2VuePlugin(options: CreateMarkdownOptions = {}): PluginOption {
+  let md: ReturnType<typeof useMarkdown>
+  const cache = new LRUCache<string, { hash: string, code: string }>({
+    max: 500,
+    ttl: 1000 * 60 * 10,
+    allowStale: true,
+    updateAgeOnGet: true,
+  })
+
+  async function transform(code: string, id: string) {
+    const hash = shortHash(code)
+    const cached = cache.get(id)
+    if (cached && cached.hash === hash) {
+      return cached.code
+    }
+    const env: MarkdownItEnv = {
+      id,
+    }
+    const html = await md.renderAsync(code, env)
+    const vueCode = md2Vue(html, env)
+    cache.set(id, { hash, code: vueCode })
+    return vueCode
+  }
+
+  function shouldSkipTransform(id: string) {
+    if (id.includes('?vue'))
+      return true
+
+    const query = id.split('?')[1]
+    if (!query)
+      return false
+    const params = new URLSearchParams(query)
+    return params.has('raw') || params.has('url')
+  }
+
+  return {
+    enforce: 'pre',
+    name: 'vite:md2vue',
+    configResolved(config) {
+      md = useMarkdown({
+        root: pathe.resolve(config.root ?? process.cwd(), '.'),
+        ...options,
+      })
+    },
+    transform: {
+      filter: {
+        id: /\.md($|\?)/,
+      },
+      async handler(code, id) {
+        if (shouldSkipTransform(id))
+          return null
+        return transform(code, id)
+      },
+    },
+    handleHotUpdate(ctx) {
+      const { file, read } = ctx
+      if (!file.endsWith('.md'))
+        return
+
+      const defaultRead = read
+      ctx.read = async () => {
+        const code = await defaultRead()
+        return transform(code, file)
+      }
+    },
+  }
+}

package/src/plugins/container.ts

@@ -0,0 +1,135 @@
+import type MarkdownIt from 'markdown-it'
+import type { RenderRule } from 'markdown-it/lib/renderer.mjs'
+import type Token from 'markdown-it/lib/token.mjs'
+import type { Options } from './pre-wrapper'
+import container from 'markdown-it-container'
+import { nanoid } from 'nanoid'
+import { extractTitle, getAdaptiveThemeMarker } from './pre-wrapper'
+
+export function containerPlugin(md: MarkdownIt, options: Options, containerOptions?: ContainerOptions) {
+  md.use(...createContainer('tip', containerOptions?.tipLabel || 'TIP', md))
+    .use(...createContainer('info', containerOptions?.infoLabel || 'INFO', md))
+    .use(
+      ...createContainer(
+        'warning',
+        containerOptions?.warningLabel || 'WARNING',
+        md,
+      ),
+    )
+    .use(
+      ...createContainer(
+        'danger',
+        containerOptions?.dangerLabel || 'DANGER',
+        md,
+      ),
+    )
+    .use(
+      ...createContainer(
+        'details',
+        containerOptions?.detailsLabel || 'Details',
+        md,
+      ),
+    )
+  // explicitly escape Vue syntax
+    .use(container as any, 'v-pre', {
+      render: (tokens: Token[], idx: number) =>
+        tokens[idx]!.nesting === 1 ? `<div v-pre>\n` : `</div>\n`,
+    })
+    .use(container as any, 'raw', {
+      render: (tokens: Token[], idx: number) =>
+        tokens[idx]!.nesting === 1 ? `<div class="vp-raw">\n` : `</div>\n`,
+    })
+    .use(...createCodeGroup(options))
+}
+
+type ContainerArgs = [any, string, { render: RenderRule }]
+
+function createContainer(
+  klass: string,
+  defaultTitle: string,
+  md: MarkdownIt,
+): ContainerArgs {
+  return [
+    container,
+    klass,
+    {
+      render(tokens, idx, _options, env) {
+        const token = tokens[idx]!
+        const info = token.info.trim().slice(klass.length).trim()
+        const attrs = md.renderer.renderAttrs(token)
+        if (token.nesting === 1) {
+          const title = md.renderInline(info || defaultTitle, {
+            references: env.references,
+          })
+          if (klass === 'details')
+            return `<details class="${klass} custom-block"${attrs}><summary>${title}</summary>\n`
+          return `<div class="${klass} custom-block"${attrs}><p class="custom-block-title">${title}</p>\n`
+        }
+        else { return klass === 'details' ? `</details>\n` : `</div>\n` }
+      },
+    },
+  ]
+}
+
+function createCodeGroup(options: Options): ContainerArgs {
+  return [
+    container,
+    'code-group',
+    {
+      render(tokens, idx) {
+        if (tokens[idx]!.nesting === 1) {
+          const name = nanoid(5)
+          let tabs = ''
+          let checked = 'checked="checked"'
+
+          for (
+            let i = idx + 1;
+            !(
+              tokens[i]!.nesting === -1
+              && tokens[i]!.type === 'container_code-group_close'
+            );
+            ++i
+          ) {
+            const token = tokens[i]!
+            const isHtml = token.type === 'html_block'
+
+            if (
+              (token.type === 'fence' && token.tag === 'code')
+              || isHtml
+            ) {
+              const title = extractTitle(
+                isHtml ? token.content : token.info,
+                isHtml,
+              )
+
+              if (title) {
+                const id = nanoid(7)
+                tabs += `<input type="radio" name="group-${name}" id="tab-${id}" ${checked}><label for="tab-${id}">${title}</label>`
+
+                if (checked && !isHtml)
+                  token.info += ' active'
+                checked = ''
+              }
+            }
+          }
+
+          return `<div class="vp-code-group${getAdaptiveThemeMarker(
+            options,
+          )}"><div class="tabs">${tabs}</div><div class="blocks">\n`
+        }
+        return `</div></div>\n`
+      },
+    },
+  ]
+}
+
+export interface ContainerOptions {
+  infoLabel?: string
+  noteLabel?: string
+  tipLabel?: string
+  warningLabel?: string
+  dangerLabel?: string
+  detailsLabel?: string
+  importantLabel?: string
+  cautionLabel?: string
+}