@mpxjs/vuese-website v1.0.7-alpha.0

介绍

本项目 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)
}

markdown扩展语法

为了完成文档示例一体化的目标，我们制定了一些语法来提取模块儿源代码。

假设你的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代码

用于提取目标文件中的template代码

<!-- @example: btn-primary -> template -->

提取script代码

用于提取目标文件中的script代码

<!-- @example: btn-primary -> script -->

提取style代码

用于提取目标文件中的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>

这样能够更好的将多个模块儿的代码组织到一起。