Skip to content

Commit 7aa71d0

Browse files
WeilinerLWeilinerL
committed
docs: ✏️ update
1 parent f83489a commit 7aa71d0

File tree

3 files changed

+339
-37
lines changed

3 files changed

+339
-37
lines changed

‎README.md

+297-3
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,299 @@
1-
# Document
1+
# 介绍
2+
本项目 fork 自 [vuese](https://vuese.github.io/website/zh/)，用于 [mpx](https://www.mpxjs.cn/) 项目的文档定制化生成。(感谢 [vuese](https://vuese.github.io/website/zh/) 的相关开发者)
23

3-
本项目 fork 自 [vuese](https://vuese.github.io/website/zh/)，高度定制化用于 mpx-cube-ui 的文档生成
4+
## 快速上手
45

5-
感谢 [vuese](https://vuese.github.io/website/zh/) 相关开发者
6+
<card>
7+
8+
### 安装
9+
10+
```bash
11+
npm install @mpxjs/vuese-website -g
12+
```
13+
14+
### 项目配置
15+
16+
假设你的项目为`monorepo`，目录结构为：
17+
```plaintext
18+
packages
19+
├── example
20+
| └── pages
21+
├── mpx-cube-ui // 换成你的组件库
22+
| └── src
23+
| └── components
24+
└── website
25+
├── package.json
26+
└── website.js
27+
```
28+
29+
其中`example`目录主要是为了演示组件库中组件的用法，启动后会打开一个h5，也是文档站点模拟器中显示的内容。
30+
31+
`website`文件夹为文档部署相关的内容，其中package.json内容如下：
32+
```json
33+
{
34+
"name": "website",
35+
"version": "1.0.0",
36+
"dependencies": {
37+
"vue": "^3.0.0",
38+
"vitepress": "^1.2.3"
39+
}
40+
}
41+
42+
```
43+
44+
在`website`文件夹下新建`website.js`文件，并写入以下内容：
45+
```javascript
46+
const path = require('path')
47+
const website = require('@mpxjs/vuese-website').default
48+
49+
website({
50+
srcDirPath: path.resolve(__dirname, '../mpx-cube-ui/src/components'), // 组件库src目录下的components目录
51+
exampleDirPath: path.resolve(__dirname, '../example/pages'), // example目录下的pages目录
52+
outputPath: path.resolve(__dirname, './docs/components'),
53+
doscPath: path.resolve(__dirname, './docs'),
54+
})
55+
56+
```
57+
58+
其中`组件库src目录下的components目录`结构如下所示：
59+
```plaintext
60+
packages/mpx-cube-ui/src/components
61+
├── button
62+
| ├── index.mpx
63+
| ├── index.ts
64+
└── button-group
65+
├── index.mpx
66+
└── index.ts
67+
```
68+
`exampleDirPath`中的`pages`目录结构如下所示：
69+
```plaintext
70+
packages/example/pages
71+
├── button
72+
| ├── README.md
73+
| ├── btn-icon.mpx
74+
| ├── btn-inline.mpx
75+
| ├── btn-light.mpx
76+
| ├── btn-loading.mpx
77+
| ├── btn-outline.mpx
78+
| ├── btn-primary.mpx
79+
| ├── btn-secondary.mpx
80+
| └── index.mpx
81+
├── button-group
82+
| ├── README.md
83+
| ├── button-group-one.mpx
84+
| ├── button-group-two.mpx
85+
| ├── button-group-vertical-two.mpx
86+
| ├── button-group-with-context.mpx
87+
| └── index.mpx
88+
├── index.mpx
89+
└── index.ts
90+
```
91+
92+
### 文档生成
93+
94+
文档由[vitepress](https://vitepress.dev/zh/guide/what-is-vitepress)驱动，需要在`website`目录中安装对应的依赖：
95+
```bash
96+
npm install vitepress@^1.2.3 vue@^3.0.0
97+
```
98+
99+
然后在`website`目录下执行以下命令：
100+
101+
```bash
102+
vuese-website
103+
```
104+
即可在项目根目录下生成基础的docs配置：
105+
```plaintext
106+
docs
107+
├── .vitepress
108+
| ├── config.mjs
109+
| ├── sidebar
110+
| | └── sidebar.js
111+
| └── theme
112+
| ├── github-light.json
113+
| └── index.mjs
114+
├── components
115+
| ├── button-group.md
116+
| └── button.md
117+
├── guide
118+
| └── intro.md
119+
└── index.md
120+
```
121+
122+
在`website`的`package.json`中添加一条命令：
123+
```diff
124+
+ "serve:doc": "node website.js"
125+
```
126+
127+
然后在目录下执行以下命令即可构建文档。
128+
129+
```bash
130+
npm run serve:doc
131+
```
132+
133+
文档启动后，默认的访问路径为：
134+
```bash
135+
http://localhost:5173/mpx-ui/guide/intro.html
136+
```
137+
138+
### 模拟器
139+
140+
模拟器的默认路由为`http://localhost:8090`，可以通过更改`docs/.vitepress/config.mjs`中的`iframeConfig`来配置预览路径：
141+
```javascript
142+
iframeConfig: {
143+
path: {
144+
dev: 'http://localhost:8090',
145+
prod: '8090'
146+
}
147+
}
148+
```
149+
150+
**注意：这里的端口号要和你的`example`项目中的`vue.config.js`配置的端口号一致**
151+
```javascript
152+
devServer: {
153+
port: 8090
154+
}
155+
```
156+
157+
检查无误后启动example项目即可完成文档中模拟器的展示。
158+
159+
### 父子路由同步
160+
161+
父子路由同步涉及到`iframe`通信，为此我们提供了以下方法来进行路由同步：
162+
```javascript
163+
declare module '@mpxjs/vuese-website/iframe-sync' {
164+
/**
165+
* 监听子路由的变化
166+
* @param callback
167+
* @returns
168+
*/
169+
export const onPathchange: (callback?: (path: string) => void) => () => void;
170+
/**
171+
* 同步路由到子窗口
172+
* @param to
173+
*/
174+
export const syncPathToChild: (to: string) => void;
175+
}
176+
```
177+
178+
你需要在`example`项目的`app.ts`中，监听主窗口路由的变化：
179+
```typescript
180+
import mpx, { createApp } from '@mpxjs/core'
181+
import { onPathchange } from '@mpxjs/vuese-website/dist/iframe-sync'
182+
183+
const isIframe = __mpx_mode__ === 'web' && window.parent !== window
184+
if (isIframe) {
185+
onPathchange((to) => {
186+
mpx.redirectTo({
187+
// 这里需要适配你的项目路径
188+
url: `/pages/${to && to !== 'intro' ? `${to}/` : ''}index`
189+
})
190+
})
191+
}
192+
```
193+
194+
同时如果`example`中涉及到路由变化，也需要同步给主窗口：
195+
```typescript
196+
const isIframe = __mpx_mode__ === 'web' && window.parent !== window
197+
if (isIframe) {
198+
syncPathToChild(componentName)
199+
}
200+
```
201+
202+
### markdown扩展语法
203+
为了完成[文档示例一体化](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)的目标，我们制定了一些语法来提取模块儿源代码。
204+
205+
假设你的`example`目录有如下结构：
206+
```plaintext
207+
example/pages
208+
├── button
209+
| ├── README.md
210+
| ├── btn-icon.mpx
211+
| ├── btn-inline.mpx
212+
| ├── btn-light.mpx
213+
| ├── btn-loading.mpx
214+
| ├── btn-outline.mpx
215+
| ├── btn-primary.mpx
216+
| ├── btn-secondary.mpx
217+
| └── index.mpx
218+
├── button-group
219+
| ├── README.md
220+
| ├── button-group-one.mpx
221+
| ├── button-group-two.mpx
222+
| ├── button-group-vertical-two.mpx
223+
| ├── button-group-with-context.mpx
224+
| └── index.mpx
225+
├── index.mpx
226+
└── index.ts
227+
```
228+
229+
基本的替换语法如下：
230+
231+
```markdown
232+
<!-- @example: ${README.md同级目录下的文件名称} -->
233+
```
234+
235+
236+
#### 提取文件代码
237+
用于提取目标文件的所有代码
238+
239+
```markdown
240+
<!-- @example: btn-primary -->
241+
```
242+
243+
#### 提取`template`代码
244+
用于提取目标文件中的`template`代码
245+
246+
```markdown
247+
<!-- @example: btn-primary -> template -->
248+
```
249+
250+
#### 提取`script`代码
251+
用于提取目标文件中的`script`代码
252+
253+
```markdown
254+
<!-- @example: btn-primary -> script -->
255+
```
256+
257+
#### 提取`style`代码
258+
用于提取目标文件中的`style`代码
259+
260+
```markdown
261+
<!-- @example: btn-primary -> style -->
262+
```
263+
264+
#### 代码成组
265+
用于把不同文件的代码提取到同一个代码块儿中
266+
267+
```markdown
268+
<!-- @group: group-name -> start -->
269+
270+
<!-- @example: btn-primary -> template no-wrap -->
271+
<!-- @example: btn-secondary -> template no-wrap -->
272+
<!-- @example: btn-light -> template -->
273+
274+
<!-- @group: group-name -> end -->
275+
```
276+
277+
其中`no-wrap`会去掉代码块的包裹，如：
278+
279+
```markdown
280+
<!-- @example: btn-primary -> template no-wrap -->
281+
```
282+
283+
渲染结果如下：
284+
285+
```html
286+
<cube-button primary>主要按钮</cube-button>
287+
```
288+
289+
而去掉`no-wrap`后，则会渲染如下代码：
290+
291+
```html
292+
<template>
293+
<cube-button primary>主要按钮</cube-button>
294+
</template>
295+
```
296+
297+
这样能够更好的将多个模块儿的代码组织到一起。
298+
299+
</card>

‎packages/website/template/docs/guide/intro.md

+21-17
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,22 @@ npm install @mpxjs/vuese-website -g
1313

1414
### 项目配置
1515

16-
假设你所在的目录为基于组件库搭建的`example`目录，这个目录主要是为了演示组件库组件的用法，启动后的效果如右边模拟器所示。👉
16+
假设你的项目为`monorepo`，目录结构为：
17+
```plaintext
18+
packages
19+
├── example
20+
| └── pages
21+
├── mpx-cube-ui // 换成你的组件库
22+
| └── src
23+
| └── components
24+
└── website
25+
├── package.json
26+
└── website.js
27+
```
1728

18-
在`example`平级目录下新建`website`文件夹，添加package.json文件：
29+
其中`example`目录主要是为了演示组件库组件的用法，启动后的效果如右边模拟器所示。👉
30+
31+
`website`文件夹为文档部署相关的内容，其中package.json内容如下：
1932
```json
2033
{
2134
"name": "website",
@@ -34,8 +47,8 @@ const path = require('path')
3447
const website = require('@mpxjs/vuese-website').default
3548

3649
website({
37-
srcDirPath: path.resolve(__dirname, '组件库src目录下的components目录'),
38-
exampleDirPath: path.resolve(__dirname, 'example目录下的pages目录'),
50+
srcDirPath: path.resolve(__dirname, '../mpx-cube-ui/src/components'), // 组件库src目录下的components目录
51+
exampleDirPath: path.resolve(__dirname, '../example/pages'), // example目录下的pages目录
3952
outputPath: path.resolve(__dirname, './docs/components'),
4053
doscPath: path.resolve(__dirname, './docs'),
4154
})
@@ -44,7 +57,7 @@ website({
4457

4558
其中`组件库src目录下的components目录`结构如下所示：
4659
```plaintext
47-
src/components
60+
packages/mpx-cube-ui/src/components
4861
├── button
4962
| ├── index.mpx
5063
| ├── index.ts
@@ -54,7 +67,7 @@ src/components
5467
```
5568
`exampleDirPath`中的`pages`目录结构如下所示：
5669
```plaintext
57-
example/pages
70+
packages/example/pages
5871
├── button
5972
| ├── README.md
6073
| ├── btn-icon.mpx
@@ -76,16 +89,6 @@ example/pages
7689
└── index.ts
7790
```
7891

79-
假设你的项目为`monorepo`，此时的目录结构为：
80-
```plaintext
81-
monorepo
82-
├── mpx-cube-ui // 换成你的组件库
83-
├── example
84-
└── website
85-
├── website.js
86-
└── package.json
87-
```
88-
8992
### 文档生成
9093

9194
文档由[vitepress](https://vitepress.dev/zh/guide/what-is-vitepress)驱动，需要在`website`目录中安装对应的依赖：
@@ -106,6 +109,7 @@ docs
106109
| ├── sidebar
107110
| | └── sidebar.js
108111
| └── theme
112+
| ├── github-light.json
109113
| └── index.mjs
110114
├── components
111115
| ├── button-group.md
@@ -143,7 +147,7 @@ iframeConfig: {
143147
}
144148
```
145149

146-
**注意：这里的端口要和你的`example`项目中的`vue.config.js`文件中配置的端口号一致**
150+
**注意：这里的端口号要和你的`example`项目中的`vue.config.js`配置的端口号一致**
147151
```javascript
148152
devServer: {
149153
port: 8090

0 commit comments

Comments
 (0)