feat: site api and add plugin-api-doc(remain to improve)

package.json

@@ -82,6 +82,7 @@
   "author": "tdesign",
   "license": "MIT",
   "dependencies": {
+    "@babel/plugin-proposal-decorators": "^7.23.2",
     "@babel/plugin-syntax-jsx": "^7.22.5",
     "@babel/preset-react": "^7.22.15",
     "@babel/preset-typescript": "^7.23.0",
@@ -150,7 +151,7 @@
     "omi-twind": "^0.0.4",
     "prismjs": "^1.24.0",
     "sortablejs": "^1.15.0",
-    "tdesign-icons-omi": "^0.0.10",
+    "tdesign-icons-omi": "^0.0.12",
     "tinycolor2": "^1.6.0",
     "twind": "^0.16.16",
     "validator": "^13.9.0"

site/plugin-api-doc/demo.js

@@ -0,0 +1,39 @@
+/* eslint-disable */
+import path from 'path'
+
+export default function renderDemo(md, container) {
+  console.log('renderDemo')
+  md.use(container, 'demo', {
+    validate(params) {
+      return params.trim().match(/^demo\s+([\\/.\w-]+)(\s+(.+?))?(\s+--dev)?$/)
+    },
+    render(tokens, idx) {
+      if (tokens[idx].nesting === 1) {
+        const match = tokens[idx].info.trim().match(/^demo\s+([\\/.\w-]+)(\s+(.+?))?(\s+--dev)?$/)
+        const [, demoPath, componentName = ''] = match
+        const demoPathOnlyLetters = demoPath.replace(/[^a-zA-Z\d]/g, '')
+        const demoName = path.basename(demoPath)
+        const demoDefName = `Demo${demoPathOnlyLetters}`
+        const demoCodeDefName = `Demo${demoPathOnlyLetters}Code`
+        const tpl = `
+          <td-doc-demo component-name="${componentName.trim()}" :code=${demoCodeDefName} demo-name="${demoName}" language="markup">
+            <div slot="action">
+              <Stackblitz demo-name="${demoName}" component-name="${componentName}" :code=${demoCodeDefName} />
+            </div>
+            <div class="tdesign-demo-item__body">
+              <${demoDefName} />
+            </div>
+          </td-doc-demo>
+        `
+
+        tokens.tttpl = tpl
+
+        return `<div class="tdesign-demo-wrapper tdesign-demo-item--${componentName.trim()}-${demoName} tdesign-demo-item--${componentName.trim()}">`
+      }
+      if (tokens.tttpl) {
+        return `${tokens.tttpl || ''}</div>`
+      }
+      return ''
+    },
+  })
+}

site/plugin-api-doc/index.js

@@ -0,0 +1,25 @@
+import vitePluginTdoc from 'vite-plugin-tdoc'
+import renderDemo from './demo'
+import transforms from './transforms'
+
+export default () =>
+  vitePluginTdoc({
+    transforms, // 解析markdown 数据
+    markdown: {
+      anchor: {
+        tabIndex: false,
+        config: (anchor) => ({
+          permalink: anchor.permalink.linkInsideHeader({ symbol: '' }),
+        }),
+      },
+      toc: {
+        listClass: 'tdesign-toc_list',
+        itemClass: 'tdesign-toc_list_item',
+        linkClass: 'tdesign-toc_list_item_a',
+        containerClass: 'tdesign-toc_container',
+      },
+      container(md, container) {
+        renderDemo(md, container)
+      },
+    },
+  })

site/plugin-api-doc/md-to-omi.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+import fs from 'fs'
+import path from 'path'
+import matter from 'gray-matter'
+import { getGitTimestamp } from '../../src/_common/docs/compile'
+import { transformSync } from '@babel/core'
+
+const DEFAULT_TABS = [
+  { tab: 'demo', name: '示例' },
+  { tab: 'api', name: 'API' },
+  { tab: 'design', name: '指南' },
+]
+
+const DEFAULT_EN_TABS = [
+  { tab: 'demo', name: 'DEMO' },
+  { tab: 'api', name: 'API' },
+  { tab: 'design', name: 'Guideline' },
+]
+
+export default async function mdToOmi(options) {
+  const mdSegment = await customRender(options)
+
+  const omiSource = `
+    import { h, tag, WeElement } from 'omi'
+
+    export default class ButtonMd extends WeElement {
+      render() {
+        return <div style={isShow('api')} name="API" dangerouslySetInnerHTML={{ __html: ${JSON.stringify(
+          mdSegment.apiMd,
+        )} }}></div>
+      }
+    }
+    `
+
+  const result = transformSync(omiSource, {
+    babelrc: false,
+    configFile: false,
+    sourceMaps: true,
+    generatorOpts: {
+      decoratorsBeforeExport: true,
+    },
+    plugins: [[require('@babel/plugin-transform-react-jsx'), { isTSX: true }]],
+  })
+
+  return { code: result.code, map: result.map }
+}
+
+// 解析 markdown 内容
+async function customRender({ source, file, md }) {
+  const { content, data } = matter(source)
+  const lastUpdated = (await getGitTimestamp(file)) || Math.round(fs.statSync(file).mtimeMs)
+  // console.log('data', data);
+  const isEn = file.endsWith('en-US.md')
+
+  // md top data
+  const pageData = {
+    spline: '',
+    toc: true,
+    title: '',
+    description: '',
+    isComponent: false,
+    tdDocHeader: true,
+    tdDocTabs: !isEn ? DEFAULT_TABS : DEFAULT_EN_TABS,
+    apiFlag: /#+\s*API/,
+    docClass: '',
+    lastUpdated,
+    designDocLastUpdated: lastUpdated,
+    ...data,
+  }
+
+  // md filename
+  const reg = file.match(/([\w-]+)\.?([\w-]+)?\.md/)
+  const componentName = reg && reg[1]
+
+  // split md
+  let [demoMd = '', apiMd = ''] = content.split(pageData.apiFlag)
+
+  const mdSegment = {
+    ...pageData,
+    componentName,
+    apiMd: '<td-doc-empty></td-doc-empty>',
+  }
+
+  mdSegment.apiMd = md.render.call(md, `${pageData.toc ? '[toc]\n' : ''}${apiMd.replace(/<!--[\s\S]+?-->/g, '')}`).html
+
+  return mdSegment
+}

site/plugin-api-doc/transforms.js

@@ -0,0 +1,64 @@
+import path from 'path'
+import fs from 'fs'
+
+import mdToOmi from './md-to-omi'
+
+let demoImports = {}
+let demoCodesImports = {}
+
+export default {
+  before({ source, file }) {
+    const resourceDir = path.dirname(file)
+    const reg = file.match(/([\w-]+)\.?([\w-]+)?\.md/)
+    const fileName = reg && reg[0]
+    const componentName = reg && reg[1]
+    const localeName = reg && reg[2]
+
+    // 统一换成 common 公共文档内容
+    if (fileName && source.includes(':: BASE_DOC ::')) {
+      const localeDocPath = path.resolve(__dirname, `../../src/_common/docs/web/api/${fileName}`)
+      const defaultDocPath = path.resolve(
+        __dirname,
+        `../../src/_common/docs/web/api/${localeName ? `${componentName}.${localeName}` : componentName}.md`,
+      )
+      let baseDoc = ''
+
+      if (fs.existsSync(localeDocPath)) {
+        // 优先载入语言版本
+        baseDoc = fs.readFileSync(localeDocPath, 'utf-8')
+      } else if (fs.existsSync(defaultDocPath)) {
+        // 回退中文默认版本
+        baseDoc = fs.readFileSync(defaultDocPath, 'utf-8')
+      } else {
+        console.error(`未找到 ${defaultDocPath} 文件`)
+      }
+      source = source.replace(':: BASE_DOC ::', baseDoc)
+    }
+
+    return source
+  },
+  render({ source, file, md }) {
+    // console.log('source: ', source, ' file: ', file, ' md: ', md)
+    const demoDefsStr = Object.keys(demoImports)
+      .map((key) => demoImports[key])
+      .join(';\n')
+    const demoCodesDefsStr = Object.keys(demoCodesImports)
+      .map((key) => demoCodesImports[key])
+      .join(';\n')
+
+    const demoInstallStr = Object.keys(demoImports).join(',')
+    const demoCodeInstallStr = Object.keys(demoCodesImports).join(',')
+
+    const sfc = mdToOmi({
+      md,
+      file,
+      source,
+      demoDefsStr,
+      demoCodesDefsStr,
+      demoInstallStr,
+      demoCodeInstallStr,
+    })
+
+    return sfc
+  },
+}