Skip to content

Commit 45bab22

Browse files
seepineseepine
committed
first commit
0 parents  commit 45bab22

File tree

19 files changed

+1085
-0
lines changed

19 files changed

+1085
-0
lines changed

‎.gitignore‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
node_modules
2+
.DS_Store
3+
__MACOSX
4+
dist
5+
dist-ssr
6+
*.local
7+
8+
# local env files
9+
.env.local
10+
.env.*.local
11+
12+
# Log files
13+
npm-debug.log*
14+
yarn-debug.log*
15+
yarn-error.log*
16+
pnpm-debug.log*
17+
18+
# Editor directories and files
19+
.idea
20+
*.suo
21+
*.ntvs*
22+
*.njsproj
23+
*.sln
24+
*.sw?
25+
26+
# lock
27+
package-lock.json
28+
yarn.lock
29+
30+
.temp
31+
.cache

‎README.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# vuepress2-plugin-demo-block
2+
## 介绍
3+
基于Vuepress2的插件，它可以帮助你在编写组件库文档的时候增加示例代码和预览。
4+
5+
## 安装
6+
7+
### 安装 VuePress
8+
9+
请参考 Vuepress2 官方文档，[点此查看](https://v2.vuepress.vuejs.org/zh/guide/getting-started.html)
10+
11+
### 安装插件
12+
13+
使用 `yarn` 安装 `vuepress2-plugin-demo-block` 插件
14+
15+
```bash
16+
yarn add vuepress2-plugin-demo-block -D
17+
```
18+
19+
或者使用 `npm` 安装它：
20+
21+
```bash
22+
npm i vuepress2-plugin-demo-block --save-dev
23+
```
24+
25+
如果你的网络环境不佳，推荐使用 [cnpm](https://github.com/cnpm/cnpm)。
26+
27+
### 配置插件
28+
29+
打开 .vuepress/config.js 文件，然后在合适的位置引用插件：
30+
31+
- **配置扫描路径** `componentsDir`
32+
33+
```js
34+
module.exports = {
35+
...
36+
plugins: [[
37+
'vuepress2-plugin-demo-block',
38+
{
39+
componentsDir: path.resolve(__dirname, './../examples')
40+
}
41+
]],
42+
...
43+
}
44+
```
45+
::: warning 注意
46+
componentsDir 必传，为动态注册组件的基础路径，目录结构可参考 element-plus
47+
:::
48+
49+
## 引入组件
50+
可在`docs/.vuepress/clientAppEnhance.js`引入组件，需要注意的是，第三方库可能还需要依赖，例如`ant-design-vue`还需要`less`和`less-loader`，请自行安装
51+
52+
```js
53+
import { defineClientAppEnhance } from "@vuepress/client";
54+
55+
// import Antd from "ant-design-vue";
56+
// import "ant-design-vue/dist/antd.css";
57+
58+
// import ElementPlus from "element-plus";
59+
// import "element-plus/dist/index.css";
60+
61+
// import ArcoVue from '@arco-design/web-vue';
62+
// import ArcoVueIcon from '@arco-design/web-vue/es/icon';
63+
// import '@arco-design/web-vue/dist/arco.css';
64+
65+
export default defineClientAppEnhance(({ app, router, siteData }) => {
66+
// app.use(Antd)
67+
// app.use(ElementPlus)
68+
// app.use(ArcoVue);
69+
// app.use(ArcoVueIcon);
70+
});
71+
```

‎docs/.vuepress/clientAppEnhance.js‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { defineClientAppEnhance } from "@vuepress/client";
2+
3+
// import Antd from "ant-design-vue";
4+
// import "ant-design-vue/dist/antd.css";
5+
6+
// import ElementPlus from "element-plus";
7+
// import "element-plus/dist/index.css";
8+
9+
// import ArcoVue from '@arco-design/web-vue';
10+
// import ArcoVueIcon from '@arco-design/web-vue/es/icon';
11+
// import '@arco-design/web-vue/dist/arco.css';
12+
13+
export default defineClientAppEnhance(({ app, router, siteData }) => {
14+
// app.use(Antd)
15+
// app.use(ElementPlus)
16+
// app.use(ArcoVue);
17+
// app.use(ArcoVueIcon);
18+
});

‎docs/.vuepress/config.js‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
const { path } = require("@vuepress/utils");
2+
3+
module.exports = {
4+
host: "0.0.0.0",
5+
title: "vuepress2-plugin-demo-block",
6+
description: "编写组件库文档的增加 Vue 展示和代码示例",
7+
port: 6688,
8+
// head: [
9+
// [
10+
// "link",
11+
// {
12+
// rel: "icon",
13+
// href: "/favicon.ico",
14+
// },
15+
// ],
16+
// ],
17+
locales: {
18+
"/": {
19+
lang: "zh-CN", // 将会被设置为 <html> 的 lang 属性
20+
},
21+
},
22+
themeConfig: {
23+
navbar: [
24+
{
25+
text: "首页",
26+
link: "/",
27+
},
28+
{
29+
text: "指南",
30+
children: [
31+
"/guide/get-started.md",
32+
"/guide/install.md",
33+
"/guide/demo.md",
34+
],
35+
},
36+
{
37+
text: "GitHub",
38+
link: "https://github.com/seepine/vuepress2-plugin-demo-block.git",
39+
},
40+
],
41+
sidebar: {
42+
"/guide/": [
43+
{
44+
text: "指南",
45+
isGroup: true,
46+
children: [
47+
{
48+
text: "介绍",
49+
children: [
50+
"/guide/get-started.md",
51+
"/guide/install.md",
52+
"/guide/demo.md",
53+
],
54+
},
55+
],
56+
},
57+
],
58+
},
59+
},
60+
plugins: [
61+
[
62+
require("./../../src"),
63+
{
64+
componentsDir: path.resolve(__dirname, "./../examples"),
65+
},
66+
],
67+
],
68+
markdown: {
69+
lineNumbers: true,
70+
},
71+
};

‎docs/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
home: true
3+
navbar: true
4+
heroImage:
5+
actions:
6+
- text: 快速上手 →
7+
link: /guide/get-started.html
8+
type: primary
9+
features:
10+
- title: 组件示例
11+
details: 无需重复编写组件展示和示例代码
12+
- title: 动态引入
13+
details: 支持动态引入配置的组件，无需手动加载
14+
- title: vuepress2
15+
details: 支持vuepress2和vue3
16+
footerHtml: true
17+
---

‎docs/examples/button/base.vue‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<template>
2+
<button>按钮</button>
3+
<button>{{btnText}}</button>
4+
</template>
5+
6+
<script setup lang="ts">
7+
import { ref } from 'vue'
8+
const btnText = ref('hello world')
9+
</script>
10+
11+
<style>
12+
</style>

‎docs/examples/button/disabled.vue‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
<template>
2+
<button disabled>禁用按钮</button>
3+
</template>
4+
<script setup lang="ts">
5+
</script>

‎docs/guide/demo.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# 示例
2+
3+
## 基础按钮
4+
5+
::: demo
6+
button/base
7+
:::
8+
9+
## 禁用按钮
10+
11+
::: demo 这里可以输入重要提示内容
12+
button/disabled
13+
:::

‎docs/guide/get-started.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# 介绍
2+
3+
## 作用
4+
一个基于Vuepress2的插件，它可以帮助你在编写文档的时候增加 Vue 示例，它的诞生初衷是为了降低编写组件文档时增加一些相关示例的难度。
5+
6+
使用 Vuepress 编写组件示例有以下尴尬之处：
7+
1. 组件示例和示例代码本质上一样，却需要写两遍；
8+
2. Vuepress 无法渲染 组件的示例代码；
9+
Demo Container vue3 参考了 Element Plus UI 的文档渲染，实现了和它一样的，可在 Markdown 中直接编写示例的语法。
10+
* Element Plus **alert**组件的**文档编写示例**，[点此查看](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/alert.md)
11+
* Element Plus **alert**组件的**文档示例预览**，[点此查看](https://element-plus.gitee.io/zh-CN/component/alert.html)
12+
13+
## 它是如何工作的？
14+
Demo Container 使用 Vuepress 的 [chainMarkdown、extendMarkdown API](https://vuepress.vuejs.org/zh/plugin/option-api.html#extendmarkdown) 拓展了其内部的 markdown 对象，并做了以下操作：
15+
- 动态注册组件，通过扫描文件夹，批量注册文件夹下所有组件，**例如 扫描examples**
16+
- examples
17+
- button
18+
- base.vue
19+
- 基于 markdown-it-container 构建了一个识别以下代码块的插件 ``示例也可以参考`` [Element Plus](https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/alert.md) ，代码块中的内容为**动态注册组件**相关文件路径，**示例如下**
20+
```
21+
:::demo
22+
button/base
23+
:::
24+
```
25+
26+
- md内容将被转换为对应的组件引用，并通过动态读对应组件实际文本内容，转换为示例输出
27+
28+
29+
## 参考示例
30+
31+
- [vuepress-plugin-demo-container](https://github.com/calebman/vuepress-plugin-demo-container)
32+
- [Element Plus ](https://element-plus.gitee.io/zh-CN/component/alert.html)

‎docs/guide/install.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# 快速上手
2+
3+
## 安装
4+
5+
### 安装 VuePress
6+
7+
请参考 Vuepress2 官方文档，[点此查看](https://v2.vuepress.vuejs.org/zh/guide/getting-started.html)
8+
9+
### 安装插件
10+
11+
使用 `yarn` 安装 `vuepress2-plugin-demo-block` 插件
12+
13+
```bash
14+
yarn add vuepress2-plugin-demo-block -D
15+
```
16+
17+
或者使用 `npm` 安装它：
18+
19+
```bash
20+
npm i vuepress2-plugin-demo-block --save-dev
21+
```
22+
23+
如果你的网络环境不佳，推荐使用 [cnpm](https://github.com/cnpm/cnpm)。
24+
25+
### 配置插件
26+
27+
打开 .vuepress/config.js 文件，然后在合适的位置引用插件：
28+
29+
- **配置扫描路径** `componentsDir`
30+
31+
```js
32+
module.exports = {
33+
...
34+
plugins: [[
35+
'vuepress2-plugin-demo-block',
36+
{
37+
componentsDir: path.resolve(__dirname, './../examples')
38+
}
39+
]],
40+
...
41+
}
42+
```
43+
::: warning 注意
44+
componentsDir 必传，为动态注册组件的基础路径，目录结构可参考 element-plus
45+
:::
46+
47+
## 引入组件
48+
可在`docs/.vuepress/clientAppEnhance.js`引入组件，需要注意的是，第三方库可能还需要依赖，例如`ant-design-vue`还需要`less`和`less-loader`，请自行安装
49+
50+
```js
51+
import { defineClientAppEnhance } from "@vuepress/client";
52+
53+
// import Antd from "ant-design-vue";
54+
// import "ant-design-vue/dist/antd.css";
55+
56+
// import ElementPlus from "element-plus";
57+
// import "element-plus/dist/index.css";
58+
59+
// import ArcoVue from '@arco-design/web-vue';
60+
// import ArcoVueIcon from '@arco-design/web-vue/es/icon';
61+
// import '@arco-design/web-vue/dist/arco.css';
62+
63+
export default defineClientAppEnhance(({ app, router, siteData }) => {
64+
// app.use(Antd)
65+
// app.use(ElementPlus)
66+
// app.use(ArcoVue);
67+
// app.use(ArcoVueIcon);
68+
});
69+
```
70+

0 commit comments

Comments
 (0)