本项目 fork 自 vuese，用于 mpx 项目的文档定制化生成。(感谢 vuese 的相关开发者)
npm install @mpxjs/vuese-website -g假设你的项目为monorepo，目录结构为：
packages
├── example
| └── pages
├── mpx-cube-ui // 换成你的组件库
| └── src
| └── components
└── website
├── package.json
└── website.js
其中example目录主要是为了演示组件库中组件的用法，启动后会打开一个h5，也是文档站点模拟器中显示的内容。
website文件夹为文档部署相关的内容，其中package.json内容如下：
{
"name": "website",
"version": "1.0.0",
"dependencies": {
"vue": "^3.0.0",
"vitepress": "^1.2.3",
"@mpxjs/vuese-website": "^1.0.0"
}
}
在website文件夹下新建website.js文件，并写入以下内容：
const path = require('path')
const website = require('@mpxjs/vuese-website').default
website({
srcDirPath: path.resolve(__dirname, '../mpx-cube-ui/src/components'), // 组件库src目录下的components目录
exampleDirPath: path.resolve(__dirname, '../example/pages'), // example目录下的pages目录
outputPath: path.resolve(__dirname, './docs/components'),
doscPath: path.resolve(__dirname, './docs'),
})其中组件库src目录下的components目录结构如下所示：
packages/mpx-cube-ui/src/components
├── button
| ├── index.mpx
| ├── index.ts
└── button-group
├── index.mpx
└── index.ts
exampleDirPath中的pages目录结构如下所示：
packages/example/pages
├── button
| ├── README.md
| ├── btn-icon.mpx
| ├── btn-inline.mpx
| ├── btn-light.mpx
| ├── btn-loading.mpx
| ├── btn-outline.mpx
| ├── btn-primary.mpx
| ├── btn-secondary.mpx
| └── index.mpx
├── button-group
| ├── README.md
| ├── button-group-one.mpx
| ├── button-group-two.mpx
| ├── button-group-vertical-two.mpx
| ├── button-group-with-context.mpx
| └── index.mpx
├── index.mpx
└── index.ts
文档由vitepress驱动，需要在website目录中安装对应的依赖：
npm install vitepress@^1.2.3 vue@^3.0.0 @mpxjs/vuese-website@^1.0.0然后在website目录下执行以下命令：
vuese-website即可在项目根目录下生成基础的docs配置：
docs
├── .vitepress
| ├── config.mjs
| ├── sidebar
| | └── sidebar.js
| └── theme
| ├── github-light.json
| └── index.mjs
├── components
| ├── button-group.md
| └── button.md
├── guide
| └── intro.md
└── index.md
在website的package.json中添加一条命令：
+ "serve:doc": "node website.js"然后在目录下执行以下命令即可构建文档。
npm run serve:doc文档启动后，默认的访问路径为：
http://localhost:5173/mpx-ui/guide/intro.html模拟器的默认路由为http://localhost:8090，可以通过更改docs/.vitepress/config.mjs中的iframeConfig来配置预览路径：
iframeConfig: {
path: {
dev: 'http://localhost:8090',
prod: '8090'
}
}注意：这里的端口号要和你的example项目中的vue.config.js配置的端口号一致
devServer: {
port: 8090
}检查无误后启动example项目即可完成文档中模拟器的展示。
父子路由同步涉及到iframe通信，为此我们提供了以下方法来进行路由同步：
declare module '@mpxjs/vuese-website/iframe-sync' {
/**
* 监听子路由的变化
* @param callback
* @returns
*/
export const onPathchange: (callback?: (path: string) => void) => () => void;
/**
* 同步路由到子窗口
* @param to
*/
export const syncPathToChild: (to: string) => void;
}你需要在example项目的app.ts中，监听主窗口路由的变化：
import mpx, { createApp } from '@mpxjs/core'
import { onPathchange } from '@mpxjs/vuese-website/dist/iframe-sync'
const isIframe = __mpx_mode__ === 'web' && window.parent !== window
if (isIframe) {
onPathchange((to) => {
mpx.redirectTo({
// 这里需要适配你的项目路径
url: `/pages/${to && to !== 'intro' ? `${to}/` : ''}index`
})
})
}同时如果example中涉及到路由变化，也需要同步给主窗口：
const isIframe = __mpx_mode__ === 'web' && window.parent !== window
if (isIframe) {
syncPathToChild(componentName)
}为了完成文档示例一体化的目标，我们制定了一些语法来提取模块儿源代码。
假设你的example目录有如下结构：
example/pages
├── button
| ├── README.md
| ├── btn-icon.mpx
| ├── btn-inline.mpx
| ├── btn-light.mpx
| ├── btn-loading.mpx
| ├── btn-outline.mpx
| ├── btn-primary.mpx
| ├── btn-secondary.mpx
| └── index.mpx
├── button-group
| ├── README.md
| ├── button-group-one.mpx
| ├── button-group-two.mpx
| ├── button-group-vertical-two.mpx
| ├── button-group-with-context.mpx
| └── index.mpx
├── index.mpx
└── index.ts
基本的替换语法如下：
<!-- @example: ${README.md同级目录下的文件名称} -->用于提取目标文件的所有代码
<!-- @example: btn-primary -->用于提取目标文件中的template代码
<!-- @example: btn-primary -> template -->用于提取目标文件中的script代码
<!-- @example: btn-primary -> script -->用于提取目标文件中的style代码
<!-- @example: btn-primary -> style -->用于把不同文件的代码提取到同一个代码块儿中
<!-- @group: group-name -> start -->
<!-- @example: btn-primary -> template no-wrap -->
<!-- @example: btn-secondary -> template no-wrap -->
<!-- @example: btn-light -> template -->
<!-- @group: group-name -> end -->其中no-wrap会去掉代码块的包裹，如：
<!-- @example: btn-primary -> template no-wrap -->渲染结果如下：
<cube-button primary>主要按钮</cube-button>而去掉no-wrap后，则会渲染如下代码：
<template>
<cube-button primary>主要按钮</cube-button>
</template>这样能够更好的将多个模块儿的代码组织到一起。
