关于javascript:手把手使用VuePress搭建Element的组件库文档官网

本教程具备视频版本,见B站《VuePress搭建Element组件库文档》

为什么要应用VuePress?

社区外面有很多优良的文档工具能够供咱们前端程序员抉择,例如Gitbook、Hexo、Docusaurus。就集体应用而言,体验最好的文档工具是Docusaurus。

Docusaurus具备配置简略,目录结构合理、Markdown渲染配置灵便等一系列的长处。但对于Vue的开发者不太敌对的是,Docusaurus是基于React的,如果你想在其中应用Vue的写法和渲染Vue组件会变得十分困难。所以如果你是Vue的开发者,在编写Vue相干组件文档的时候,集体还是举荐应用官网的VuePress。

上面的教程会应用VuePress生成相似Element的组件文档库,包含Vue组件展现、示例代码展现、自定义主题等罕用性能。

装置

  1. 创立我的项目 vuepress-element-doc
mkdir vuepress-element-doc && cd vuepress-element-doc
  1. 初始化npm包治理并在 package.json 中新增脚本
npm init -y
// package.json

"scripts": {
  "dev": "vuepress dev docs",
  "build": "vuepress build docs"
},
  1. 装置 VuePress + Element
npm install vuepress element-ui --registry=https://registry.npm.taobao.org

因为咱们要做的是Element的组件文档页,所有这里顺便装置一下Element。你如果须要展现你本人的组件库,那么装置或引人本人的组件库的js和css即可。

创立首页

新建首页.md文件

新建 docs/README.md

---
home: true
heroImage: https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.png
heroText: Element
features:
- title: 一致性 Consistency
  details: 与现实生活统一:与现实生活的流程、逻辑保持一致,遵循用户习惯的语言和概念
- title: 反馈 Feedback
  details: 通过界面款式和交互动效让用户能够清晰的感知本人的操作
- title: 效率 Efficiency
  details: 界面简略直白,让用户疾速辨认而非回顾,缩小用户记忆负担。
footer: by饿了么
---

### 设计准则

<div style="display:flex;justify-content: space-between;padding-bottom:40px">
  <div style="display: flex;flex-direction: column;align-items: center;">
    <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/consistency.png" alt="一致性">
    <p style="margin:5px">一致性</p>
    <p style="margin:0px;font-size: 12px;color:#666">Consistency</p>
  </div>
  <div style="display: flex;flex-direction: column;align-items: center;">
    <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/feedback.png" alt="反馈">
    <p style="margin:5px">反馈</p>
    <p style="margin:0px;font-size: 12px;color:#666"> Feedback</p>
  </div>
  <div style="display: flex;flex-direction: column;align-items: center;">
    <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/efficiency.png" alt="效率">
    <p style="margin:5px">效率</p>
    <p style="margin:0px;font-size: 12px;color:#666">Efficiency</p>
  </div>
  <div style="display: flex;flex-direction: column;align-items: center;">
    <img style="width:100px" src="https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/controllability%20%20.png" alt="可控">
    <p style="margin:5px">可控</p>
    <p style="margin:0px;font-size: 12px;color:#666">Controllability</p>
  </div>
</div>

这个README.md中一共有三种语法:

  1. YAML: 顶部以 --- 包裹起来的是YAML语法的Front Matter,这个语法必须位于.md的顶部,是可选的。
  2. Markdown: 其中 ### 设计准则 局部是Markdown语法,置信大家都很相熟。
  3. HTML: 最初是咱们相熟的HTML语法,总所周知,在 .md 中是能够应用HTML语法的。

备注:docs/README.md中的图片地址是放到OSS上的地址,因为这样更方便使用。当然你也能够应用本地的公共文件,具体见Vuepress/动态资源/公共文件。

创立配置文件

新建 docs/.vuepress/config.js ,填入根本的配置信息。留神,这个文件是VuePress最外围的一个文件,有着丰盛的配置项。

module.exports = {
  theme: '',
  title: 'VuePress + Element',
  description: 'VuePress搭建Element的组件库文档教程示例代码',
  base: '/',
  port: '8080',
  themeConfig: {},
  head: [],
  plugins: [],
  markdown: {}
}

启动我的项目

应用命令运行VuePress,查看成果

npm run dev

浏览器拜访 localhost:8080 ,如果没有意外,我置信你曾经可能在页面上看到如下的成果了,这个页面就是咱们在README.md 这个文件中所编写的YAML + Markdown + HTML的整体成果。

创立组件页

新建组件页的.md文件

创立 /docs/comps/README.md , 填入内容。这里模拟的是Element官网的装置页面。

# 装置

## npm装置

举荐应用 npm 的形式装置,它能更好地和 webpack 打包工具配合应用。


npm i element-ui -S


## CDN
目前能够通过 unpkg.com/element-ui 获取到最新版本的资源,在页面上引入 js 和 css 文件即可开始应用。


<!-- 引入款式 -->
<link rel="stylesheet" href="https://unpkg.com/element-ui/lib/theme-chalk/index.css">
<!-- 引入组件库 -->
<script src="https://unpkg.com/element-ui/lib/index.js"></script>

创立 /docs/comps/select.md,填入内容。创立两个文件是不便咱们之后设置文档侧边栏, 这里模拟的是Element官网的选择器组件页面。

# Select 选择器

当选项过多时,应用下拉菜单展现并抉择内容。

## 根本用法

实用宽泛的根底单选

配置顶部导航栏

/docs/.vuepress/config.js 中配置顶部导航栏的配置字段 themeConfig.nav。代码如下:

module.exports = {
  theme: '',
  title: 'VuePress + Element',
  description: 'VuePress搭建Element的组件库文档教程示例代码',
  base: '/',
  port: '8080',
  themeConfig: { // 新增代码
    nav: [ // 配置顶部导航栏
      {
        text: '首页',
        link: '/'
      },
      {
        text: '组件',
        link: '/comps/'
      }
    ]
  },
  repo: 'http://gitlab.17zuoye.net/tanghui.li/Apollo.js',
  head: [],
  plugins: [],
  markdown: {}
}

配置组件页文档的侧边栏

/docs/.vuepress/config.js 中配置顶部导航栏的配置字段 themeConfig.sidebar。代码如下:

module.exports = {
  theme: '',
  title: 'VuePress + Element',
  description: 'VuePress搭建Element的组件库文档教程示例代码',
  base: '/',
  port: '8080',
  themeConfig: {
    nav: [
      {
        text: '首页',
        link: '/'
      },
      {
        text: '组件',
        link: '/comps/'
      }
    ],
    sidebar: { // 配置侧边栏局部
      '/comps/': ['/comps/', '/comps/select.md']
    }
  },
  head: [],
  plugins: [],
  markdown: {}
}

此时我置信你就可能在浏览器上看到这样的页面了,是不是有一点Element文档的滋味了。

组件展现成果实现

可是到目前为止,咱们还没有引入Element的组件局部,既然是一个组件库,咱们天然心愿实现像Element这样,下面有组件的展现,上面是示例的代码。这一部分咱们就来看看如何实现这个成果吧

装置Demo插件

这里咱们会应用到一个 vuepress-plugin-demo-container 这个插件,应用以下命令装置

npm install vuepress-plugin-demo-container

而后在/docs/.vuepress/config.js文件中配置上该插件

module.exports = {
  // ...
  plugins: ['demo-container'], // 配置插件
  markdown: {}
}

意识enhanceApp.js

你有没有想过咱们平时在我的项目外面应用Element,须要在 app.js 中引入Element,并调用 Vue.use(Element) 才可能在Vue中应用Element的组件,那么咱们如果想在VuePress中应用Element,咱们须要去哪里编写这段代码呢?

此时咱们须要意识一个新的文件enhanceApp.js,它算是VuePress中仅此于config.js 第二重要的文件了,当你想做一些Vue利用级别的配置时,就须要在这个文件外面配置。让咱们在新建该文件吧:/docs/.vuepress/enhanceApp.js

import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';

export default async ({
  Vue
}) => {
  if (typeof process === 'undefined') {
    Vue.use(ElementUI)
  }
}

引入Element组件

接下来咱们在方才创立的/docs/comps/select.md中应用Element试试看吧。应用上面的内容替换原有的内容吧。

# Select 选择器

当选项过多时,应用下拉菜单展现并抉择内容。

## 根本用法

实用宽泛的根底单选

::: demo 实用宽泛的根底单选
\```html(留神:须要去掉后面的‘\’!!!)
<template>
  <el-select v-model="value" placeholder="请抉择">
    <el-option
      v-for="item in options"
      :key="item.value"
      :label="item.label"
      :value="item.value">
    </el-option>
  </el-select>
</template>

<script>
  export default {
    data() {
      return {
        options: [{
          value: '选项1',
          label: '黄金糕'
        }, {
          value: '选项2',
          label: '双皮奶'
        }],
        value: ''
      }
    }
  }
</script>
\```(留神:须要去掉后面的‘\’!!!)
:::

如果一切顺利的话,我置信你此时应该可能看到以下的成果了:

部署VuePress

到目前未知,组件库的根本框架就曾经搭建实现了,剩下的就是填充内容并最终部署。当初咱们来讲一下部署环节。

执行部署命令

还记得咱们之前在 package.json 中配置VuePress部署脚本的"build": "vuepress build docs"吗?所以咱们只须要执行以下命令即可

npm run build

查看文件,你会发现此时/docs/.vuepress/dist 这个文件多了进去,dist 目录就是咱们的最终部署目录。

├── docs
│   ├── .vuepress
│   │   ├── config.js
│   │   ├── dist 
│   │   │   ├── 404.html
│   │   │   ├── assets
│   │   │   │   ├── css
│   │   │   │   │   └── 0.styles.262ade0c.css
│   │   │   │   ├── fonts
│   │   │   │   │   ├── element-icons.535877f5.woff
│   │   │   │   │   └── element-icons.732389de.ttf
│   │   │   │   ├── img
│   │   │   │   │   └── search.83621669.svg
│   │   │   │   └── js
│   │   │   │       ├── 2.ae254118.js
│   │   │   │       ├── 3.c4b624da.js
│   │   │   │       ├── 4.8c48097d.js
│   │   │   │       ├── 5.a4fed9a4.js
│   │   │   │       ├── 6.efea7d5a.js
│   │   │   │       ├── 7.fc05164e.js
│   │   │   │       ├── 8.8ee7961b.js
│   │   │   │       ├── 9.e8d922fc.js
│   │   │   │       └── app.90733c82.js
│   │   │   ├── comps
│   │   │   │   ├── index.html
│   │   │   │   └── select.html
│   │   │   └── index.html
│   │   └── enhanceApp.js
│   ├── README.md
│   └── comps
│       ├── README.md
│       └── select.md
├── package-lock.json
└── package.json

应用Web Server部署

只需把root目录指向/docs/.vuepress/dist/就能够部署到服务,这里咱们应用了本机的MAMP的Apache用做Web Server。当然你也能够应用nginx或者任何你喜爱的服务器进行部署。

此时输出Web Server所配置的端口名称,就能看见曾经部署胜利了

参考资料

  1. VuePress官网文档
  2. demoContainer插件

评论

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

这个站点使用 Akismet 来减少垃圾评论。了解你的评论数据如何被处理