Use VuePress to build Element's component library document official website

This tutorial has a video version, see B station "VuePress Building Element Component Library Document"

Why use VuePress?

There are many excellent documentation tools in the community for our front-end programmers to choose from, such as Gitbook, Hexo, Docusaurus. As far as personal use is concerned, the most experienced documentation tool is Docusaurus .

Docusaurus has a series of advantages such as simple configuration, reasonable directory structure, and flexible Markdown rendering configuration. But what is not very friendly to Vue developers is that Docusaurus is based on React. If you want to use Vue writing and rendering Vue components in it, it will become very difficult. So if you are a Vue developer, when writing Vue-related component documentation, I personally recommend using the official VuePress.

The following tutorial will use VuePress to generate a component document library similar to Element, including common functions such as Vue component display, sample code display, and custom themes.

Install

1. Create project vuepress-element-doc

mkdir vuepress-element-doc && cd vuepress-element-doc

2. Initialize npm package management and add scripts package.json

npm init -y

// package.json

"scripts": {
  "dev": "vuepress dev docs",
  "build": "vuepress build docs"
},

3. Install VuePress + Element

npm install vuepress element-ui --registry=https://registry.npm.taobao.org

Because what we are going to do is the component document page of Element, so let's install Element by the way. If you need to display your own component library, then install or introduce your own js and css component library.

Create a homepage

New home page .md file

Newly built 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>

There are three syntaxes in this README.md

1. YAML: The --- wrapped with 0610be29ced9b5 at the top is the Front Matter of YAML syntax. This syntax must be at .md and is optional.
2. Markdown: ### The design principle part is Markdown syntax, I believe everyone is familiar with it.
3. HTML: Finally, we are familiar with HTML grammar. As we all know, HTML grammar can be used .md

Note: The picture address in docs/README.md is the address on OSS because it is more convenient to use. Of course, you can also use local public files, see Vuepress/Static Resources/Public Files .

Create a configuration file

Create a new docs/.vuepress/config.js and fill in the basic configuration information. Note that this file is the core file of VuePress, with a wealth of configuration items.

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

Startup project

Use the command to run VuePress to see the effect

npm run dev

The browser visits localhost:8080 . If there is no accident, I believe you can already see the following effect on the page. This page is the overall effect of YAML + Markdown + HTML README.md


Create component page

.md file on the new component page

Create /docs/comps/README.md and fill in the content. The imitation here is the installation page Element's official website.

# 安装

## 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>

Create /docs/comps/select.md and fill in the content. Creating two files is convenient for us to set up the document sidebar later, here is the selector component page of Element's official website.

# Select 选择器

当选项过多时，使用下拉菜单展示并选择内容。

## 基本用法

适用广泛的基础单选

Configure the top navigation bar

In /docs/.vuepress/config.js Configuration field at the top navigation bar themeConfig.nav . code show as below:

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

Configure the sidebar of the component page document

In /docs/.vuepress/config.js Configuration field at the top navigation bar themeConfig.sidebar . code show as below:

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: {}
}

At this point, I believe you will be able to see such a page on your browser. Does it smell like Element documents?


Component display effect realization

But so far, we haven't introduced the component part of Element. Since it is a component library, we naturally hope to achieve something like Element, with the display of components on it, and the sample code below. In this part, let’s take a look at how to achieve this effect.

Install the demo plug-in

Here we will use a vuepress-plugin-demo-container plug-in, use the following command to install

npm install vuepress-plugin-demo-container

Then configure the plug-in in the /docs/.vuepress/config.js

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

Meet enhanceApp.js

Have you ever thought that we usually use Element in our projects, we need to introduce Element app.js Vue.use(Element) to be able to use Element components in Vue, then if we want to use Element in VuePress, where do we need to write this paragraph? What about the code?

At this point, we need to know a new file enhanceApp.js , which is the config.js than 0610be29cedf1d. When you want to do some Vue application-level configuration, you need to configure it in this file. Let's create this file: /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)
  }
}

Introduce Element components

Next, let's try using Element /docs/comps/select.md Replace the original content with the following content.

# 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>
\```(注意：需要去掉前面的‘\’！！！)
:::

If all goes well, I believe you should be able to see the following effects at this time:

Deploy VuePress

As yet unknown, the basic framework of the component library has been built, and all that is left is to fill in the content and finally deploy. Now let's talk about the deployment process.

Execute deployment commands

Remember the package.json that we configured the VuePress deployment script in "build": "vuepress build docs" ? So we only need to execute the following command

npm run build

Looking at the file, you will find that the /docs/.vuepress/dist file is extra, and the dist directory is our final deployment directory.

├── 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

Deploy using Web Server

Just point the root directory to /docs/.vuepress/dist/ to deploy to the service. Here we use the native MAMP Apache as the Web Server. Of course, you can also use nginx or any server you like to deploy.

At this time, enter the port name configured by Web Server, you can see that the deployment has been successful

Reference

1. VuePress official document
2. demoContainer plugin

Source address

1. Github-Lee-Tanghui/vuepress-element-doc