vitepress-demo-editor

介绍

一个 vitepress 文档插件,可以帮助你在编写文档的时候增加 Vue 示例,通常使用在组件库展示,支持在线编辑演示源代码且视图实时更新

支持

• 支持 vue sfc

• 支持 jsx/tsx

• 编辑器语法提示

• 编辑器代码高亮

demo 预览

promiseui (一个 vue3 组件库)

安装

npm install vitepress-demo-editor

使用

需要先安装两个插件

1. 添加 vue 插件 和 样式文件

1// .vitepress/theme/index.js
2
3import { vuePlugin } from "vitepress-demo-editor";
4import "vitepress-demo-editor/dist/style.css";
5
6export default {
7  // ...otherConfig
8  enhanceApp({ app }) {
9    app.use(vuePlugin, {
10      defaultDirection: "row", // 默认显示方向
11      ms: 30, // 编辑器防抖时间
12      handleError(errs) {}, // 错误信息
13      onMonacoCreated(monaco) {}, // monaco 创建成功时触发
14    });
15  },
16};

2. 添加 markdown 插件

1//.vitepress/config.js
2import markdownPlugin from "vitepress-demo-editor/markdownPlugin";
3const config = {
4  // ...otherConfig
5  markdown: {
6    config: (md) => {
7      md.use(markdownPlugin);
8    },
9  },
10};
11export default config;

在 markdown 中使用

sfc

1:::demo
2
3```vue
4<template>
5  <button class="demo-btn" @click="count--">-</button>
6  <b class="demo-count" :class="{ red: count >= 3 }">{{ count }}</b>
7  <button class="demo-btn" @click="count++">+</button>
8</template>
9<script setup>
10import { ref } from "vue";
11const count = ref(0);
12const text = ref("");
13</script>
14<style>
15/* 默认 scoped */
16.demo-btn {
17  padding: 0 10px;
18  border: 1px solid #ccc;
19}
20.demo-count {
21  display: inline-block;
22  text-align: center;
23  margin: 0 10px;
24  min-width: 30px;
25}
26/* global */
27
28:global(.red) {
29  color: red;
30}
31</style>
32```
33
34:::

设置column上下显示

1:::demo column
2
3```vue
4<!--  code -->
5```
6
7:::

设置 height 指定编辑器高度(有最小限制 column:200px row:300px)

指定高度 400

1:::demo height:400
2
3```vue
4<!--  code -->
5```
6
7:::

jsx/tsx

配置 vite.config.js

1// docs/vite.config.js
2import { defineConfig } from "vite";
3
4export default defineConfig({
5  define: {
6    "process.env.BABEL_TYPES_8_BREAKING": "false",
7    "process.platform": '"darwin"',
8    "Buffer.isBuffer": "undefined",
9  },
10  resolve: {
11    alias: {
12      assert: "browser-assert",
13      path: "path-browserify",
14    },
15  },
16});

使用

jsx

1:::demo column
2
3```jsx
4<!--  code -->
5```
6
7:::

tsx

1:::demo column
2
3```tsx
4<!--  code -->
5```
6
7:::

Demo 预览

promiseui-table-jsx

打包报错?

打包可能会报错,提示 Error: Missing "./preload-helper" export in "vite" package ,

原因不清楚,但有解决办法

ctrl + click 进入报错文件

搜索 vite/preload-helper 替换为 \0vite/preload-helper

'vite/preload-helper'->'\0vite/preload-helper'

高级用法

importMap

简单使用

默认只能import vue,要想import 其他库需要用addImportMap

1// .vitepress/theme/index.js
2import { vuePlugin, addImportMap } from "vitepress-demo-editor";
3import axios from "axios";
4
5export default {
6  // ...otherConfig
7  enhanceApp({ app }) {
8    app.use(vuePlugin);
9    addImportMap("axios", axios);
10  },
11};

然后在markdown中就可以使用

1:::demo
2
3```vue
4<template>...</template>
5<script setup>
6// 使用
7import axios from "axios";
8</script>
9```
10
11:::

对于 ssr 不友好的库

由于 VitePress 应用程序在生成静态构建时在 Node.js 中进行服务器渲染，因此任何 Vue 使用都必须符合通用代码要求。简而言之，确保只在 beforeMount 或mounted 钩子中访问浏览器/DOM API。

对于 ssr 不友好的库不能直接导入,否则打包会报错.以下代码可解决

1// .vitepress/theme/index.js
2import { vuePlugin, addImportMap } from "vitepress-demo-editor";
3let first = true;
4export default {
5  // ...otherConfig
6  enhanceApp({ app }) {
7    app.use(vuePlugin);
8    app.mixin({
9      async mounted() {
10        if (!first) return;
11        first = false;
12        await import("vue-promiseui").then((promiseUI) => {
13          addImportMap("promiseui-vue", promiseUI);
14          app.use(promiseUI.default);
15        });
16      },
17    });
18  },
19};

由于异步 import 导致 addImportMap 执行时机可能会慢,在这前执行的代码会报错.所以要配置vite.config.ts optimizeDeps 预构建

1export default defineConfig({
2  optimizeDeps: {
3    include: ["promiseui-vue"], //填入库名
4  },
5});

编辑器添加库提示

在tsx / jsx 中, 默认自带 import vue 有提示

如果想添加其他库代码提示 ,以vue-promiseui库为例子

1import { vuePlugin } from "vitepress-demo-editor";
2import "vitepress-demo-editor/dist/style.css";
3// 找到该库的类型文件,在vite中 以 ?raw方式导入
4import promiseuiType from "promiseui-vue/dist/promiseui/vue-promiseui.d.ts?raw";
5
6export default {
7  // ...otherConfig
8  enhanceApp({ app }) {
9    app.use(vuePlugin, {
10      onMonacoCreated(monaco) {
11        // 在此处 添加库提示
12        monaco.languages.typescript.typescriptDefaults.addExtraLib(
13          `
14          declare module 'promiseui-vue' { 
15            ${promiseuiType} 
16          }
17          `,
18          "promiseui-vue"
19        );
20      }, //
21    });
22  },
23};

黑暗模式

html 标签 class 有 dark 会自动变为黑暗模式

1<html class="dark">
2  <!-- html -->
3</html>

CHANGELOG