antdv-next/docs-base 文档站点的插件与组件集:一条开箱即用的 Vite + markdown-it 管线,负责 Markdown → Vue 渲染、demo 收集、代码高亮与在线编辑,并附带可复用的 <CodeDemo> 展示组件。
pnpm add -D @antdv-next/docs-plugins// vite.config.ts
import { mdPlugin } from '@antdv-next/docs-plugins'
export default defineConfig({
plugins: [
mdPlugin(),
],
})mdPlugin() = md2VuePlugin(Markdown → Vue SFC)+ demoPlugin(demo 收集虚拟模块),覆盖:
- shiki 双主题高亮、anchor/toc/frontmatter/emoji、tip/warning 等容器、GitHub Alerts
- demo 收集:页面里
<demo src="./demo/basic.vue">标题</demo>生成锚点目录与按需加载的 demo 模块 - 外部链接自动新标签页打开
## 代码演示 {#examples} <!-- 英文页写 ## Examples -->
<demo src="./demo/basic.vue">基本用法</demo>- demo 文件放在页面同级的
demo/目录(默认收集<root>/src/pages/**/demo/*.vue,可用include调整) - demo SFC 内的
<docs>自定义块作为该 demo 的描述文案 - 锚点统一挂到 slug 为
examples的标题下
css: {
postcss: {
plugins: [postcssIsolateStyles()],
},
},demo 的展示与在线编辑由包内组件承担,站点只需注入站点差异:
import CodeDemo from '@antdv-next/docs-plugins/component/code-demo/index.vue'
import { provideDemoContext } from '@antdv-next/docs-plugins/component/code-demo/context'
provideDemoContext({
locale: () => (route.meta?.locale === 'en-US' ? 'en-US' : 'zh-CN'),
isDark: () => isDark.value,
// 演示源码可 import 的模块(浏览器实时编译用),逐模块容错
modules: {
'antdv-next': () => import('antdv-next'),
'@antdv-next/icons': () => import('@antdv-next/icons'),
},
openPlayground: code => window.open(loadPlaygroundUrl(code), '_blank'),
// openStackBlitz / demoPageUrl / editUrl / iframeRenderer / preferredCodeType 可选
// copyCode: false 可隐藏操作栏复制按钮(默认显示)
})<CodeDemo src="/src/pages/components/button/demo/basic.vue">
基本用法
</CodeDemo>- 展开代码面板即得可编辑编辑器(Sandpack),编辑内容经
@vue/compiler-sfc+sucrase在浏览器端实时编译并替换预览 - 操作栏按钮全部由站点能力驱动:未提供的能力(如 StackBlitz)对应按钮自动隐藏;复制按钮默认显示,
copyCode: false可关闭;标题区编辑图标由editUrl提供时显示
建议在 vite 中对这些依赖做 resolve.dedupe,保证与站点共享同一实例:
resolve: {
dedupe: ['vue', 'vue-router', '@vueuse/core', 'antdv-next', '@antdv-next/icons', 'antdv-style'],
},自定义 demo UI 时引用包��自带的类型:
/// <reference types="@antdv-next/docs-plugins/component/code-demo/virtual" />| 选项 | 默认 | 说明 |
|---|---|---|
markdown.demo.headerMode |
'examples' |
demo 锚点挂到 slug 为 examples 的标题下;'section' 为跟随章节层级 |
markdown.demo.debugDemo |
true |
生产构建跳过带 debug 属性 demo 的目录收集 |
markdown.demo.wrapper |
'demo' |
demo 标签名 |
markdown.externalLink |
true |
外部链接自动 target="_blank" + rel="noopener noreferrer" |
demo.include |
/src/pages/**/demo/*.vue |
demo 收集范围 |
demo.sourceVersionOnHmr |
true |
任意 HMR 提升 sourceVersion,促使已挂载 demo 重新拉取源码 |
demo.jsFormatter |
内置 oxfmt | TS → JS 源码格式化器,可用 createOxfmtJsFormatter(style) 换风格 |
demo.renderSourceHtml / demo.virtualMode |
已移除 | 源码统一在浏览器端编译展示;virtual:demos 统一为懒加载注册表 |
mdPlugin(options)/md2VuePlugin/demoPlugincreateMarkdown/useMarkdown/loadBaseMd/loadShiki(CreateMarkdownOptions)- markdown-it 插件:
container/demo/github-alerts/image/link/pre-wrapper/stackblitz/table postcssIsolateStyles:markdown 样式隔离 PostCSS 插件tsToJs+createOxfmtJsFormatter:demo 源码 TS → JS 转换与格式化- 组件:
CodeDemo+provideDemoContext/useDemoContext(类型:DemoModule/DemoSourceData等) - 工具:
getDemoId/shortHash
pnpm install # 安装依赖
pnpm build # tsdown 构建 dist(插件部分;组件以 src 源码形态被站点引用)
pnpm dev # watch 模式
pnpm lint # eslint
pnpm typecheck # tsc --noEmit下游站点开发期可通过 pnpm link: 引用本工程联调,发布后改为正常版本依赖。