npm package: @mpxjs/vuese-website
Description: 构建示例网站
Author: QiuShuiBai
Latest version: 1.0.7-alpha.0

# 介绍
本项目 fork 自 [vuese](https://vuese.github.io/website/zh/)，用于 [mpx](https://www.mpxjs.cn/) 项目的文档定制化生成。(感谢 [vuese](https://vuese.github.io/website/zh/) 的相关开发者)

## 快速上手

<card>

### 安装

```bash
npm install @mpxjs/vuese-website -g
```

### 项目配置

假设你的项目为`monorepo`，目录结构为：
```plaintext
packages
   ├── example
   |  └── pages
   ├── mpx-cube-ui // 换成你的组件库
   |  └── src
   |     └── components
   └── website
      ├── package.json
      └── website.js
```

其中`example`目录主要是为了演示组件库中组件的用法，启动后会打开一个h5，也是文档站点模拟器中显示的内容。

`website`文件夹为文档部署相关的内容，其中package.json内容如下：
```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`文件，并写入以下内容：
```javascript
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目录`结构如下所示：
```plaintext
packages/mpx-cube-ui/src/components
├── button
|  ├── index.mpx
|  ├── index.ts
└── button-group
   ├── index.mpx
   └── index.ts
```
`exampleDirPath`中的`pages`目录结构如下所示：
```plaintext
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](https://vitepress.dev/zh/guide/what-is-vitepress)驱动，需要在`website`目录中安装对应的依赖：
```bash
npm install vitepress@^1.2.3 vue@^3.0.0 @mpxjs/vuese-website@^1.0.0
```

然后在`website`目录下执行以下命令：

```bash
vuese-website
```
即可在项目根目录下生成基础的docs配置：
```plaintext
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`中添加一条命令：
```diff
+  "serve:doc": "node website.js"
```

然后在目录下执行以下命令即可构建文档。

```bash
npm run serve:doc
```

文档启动后，默认的访问路径为：
```bash
http://localhost:5173/mpx-ui/guide/intro.html
```

### 模拟器

模拟器的默认路由为`http://localhost:8090`，可以通过更改`docs/.vitepress/config.mjs`中的`iframeConfig`来配置预览路径：
```javascript
iframeConfig: {
  path: {
    dev: 'http://localhost:8090',
    prod: '8090'
  }
}
```

**注意：这里的端口号要和你的`example`项目中的`vue.config.js`配置的端口号一致**
```javascript
devServer: {
  port: 8090
}
```

检查无误后启动example项目即可完成文档中模拟器的展示。

### 父子路由同步

父子路由同步涉及到`iframe`通信，为此我们提供了以下方法来进行路由同步：
```javascript
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`中，监听主窗口路由的变化：
```typescript
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`中涉及到路由变化，也需要同步给主窗口：
```typescript
const isIframe = __mpx_mode__ === 'web' && window.parent !== window
if (isIframe) {
  syncPathToChild(componentName)
}
```

### markdown扩展语法
为了完成[文档示例一体化](https://www.mpxjs.cn/mpx-cube-ui/guide/intro.html#%E6%96%87%E6%A1%A3%E7%A4%BA%E4%BE%8B%E4%B8%80%E4%BD%93%E5%8C%96)的目标，我们制定了一些语法来提取模块儿源代码。

假设你的`example`目录有如下结构：
```plaintext
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
```

基本的替换语法如下：

```markdown
<!-- @example: ${README.md同级目录下的文件名称} -->
```


#### 提取文件代码
用于提取目标文件的所有代码

```markdown
<!-- @example: btn-primary -->
```

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

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

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

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

#### 提取`style`代码
用于提取目标文件中的`style`代码

```markdown
<!-- @example: btn-primary -> style -->
```

#### 代码成组
用于把不同文件的代码提取到同一个代码块儿中

```markdown
<!-- @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`会去掉代码块的包裹，如：

```markdown
<!-- @example: btn-primary -> template no-wrap -->
```

渲染结果如下：

```html
<cube-button primary>主要按钮</cube-button>
```

而去掉`no-wrap`后，则会渲染如下代码：

```html
<template>
  <cube-button primary>主要按钮</cube-button>
</template>
```

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

</card>