Skip to content

Commit

Permalink
docs: ✏️ update
Browse files Browse the repository at this point in the history
  • Loading branch information
@WeilinerL
WeilinerL committed Nov 21, 2024
1 parent 352fc76 commit 407f8d1
Show file tree
Hide file tree
Showing 4 changed files with 303 additions and 11 deletions.
5 changes: 3 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ packages
"version": "1.0.0",
"dependencies": {
"vue": "^3.0.0",
"vitepress": "^1.2.3"
"vitepress": "^1.2.3",
"@mpxjs/vuese-website": "^1.0.0"
}
}

Expand Down Expand Up @@ -93,7 +94,7 @@ packages/example/pages

文档由[vitepress](https://vitepress.dev/zh/guide/what-is-vitepress)驱动，需要在`website`目录中安装对应的依赖：
```bash
npm install vitepress@^1.2.3 vue@^3.0.0
npm install vitepress@^1.2.3 vue@^3.0.0 @mpxjs/vuese-website@^1.0.0
```

然后在`website`目录下执行以下命令：
Expand Down
299 changes: 294 additions & 5 deletions packages/website/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,300 @@
# `website`
# 介绍
本项目 fork 自 [vuese](https://vuese.github.io/website/zh/)，用于 [mpx](https://www.mpxjs.cn/) 项目的文档定制化生成。(感谢 [vuese](https://vuese.github.io/website/zh/) 的相关开发者)

> TODO: description
## 快速上手

## Usage
<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;
}
```
const website = require('website');

// TODO: DEMONSTRATE API
你需要在`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>
5 changes: 3 additions & 2 deletions packages/website/template/docs/guide/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ packages
"version": "1.0.0",
"dependencies": {
"vue": "^3.0.0",
"vitepress": "^1.2.3"
"vitepress": "^1.2.3",
"@mpxjs/vuese-website": "^1.0.0"
}
}

Expand Down Expand Up @@ -93,7 +94,7 @@ packages/example/pages

文档由[vitepress](https://vitepress.dev/zh/guide/what-is-vitepress)驱动，需要在`website`目录中安装对应的依赖：
```bash
npm install vitepress@^1.2.3 vue@^3.0.0
npm install vitepress@^1.2.3 vue@^3.0.0 @mpxjs/vuese-website@^1.0.0
```

然后在`website`目录下执行以下命令：
Expand Down
5 changes: 3 additions & 2 deletions website/docs/guide/intro.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ packages
"version": "1.0.0",
"dependencies": {
"vue": "^3.0.0",
"vitepress": "^1.2.3"
"vitepress": "^1.2.3",
"@mpxjs/vuese-website": "^1.0.0"
}
}

Expand Down Expand Up @@ -93,7 +94,7 @@ packages/example/pages

文档由[vitepress](https://vitepress.dev/zh/guide/what-is-vitepress)驱动，需要在`website`目录中安装对应的依赖：
```bash
npm install vitepress@^1.2.3 vue@^3.0.0
npm install vitepress@^1.2.3 vue@^3.0.0 @mpxjs/vuese-website@^1.0.0
```

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

0 comments on commit 407f8d1

Please sign in to comment.