This tutorial is available in a video version. See VuePress building an Element Library for more information.

Why use VuePress?

There are many excellent documentation tools in the community for us front-end programmers to choose from, such as Gitbook, Hexo, Docusaurus. For personal use, the best documentation tool to experience isDocusaurus.

Docusaurus has the advantages of simple configuration, reasonable directory structure, flexible Markdown rendering configuration and so on. Less friendly to Vue developers, Docusaurus is React based, making it difficult to write Vue and render Vue components in it. So if you are a Vue developer, I personally recommend using the official VuePress when documenting vUe-related components.

The following tutorial uses VuePress to generate a Library of Element-like component documentation, including common Vue component displays, sample code displays, custom themes, and more.

The installation

  1. Create a projectvuepress-element-doc
mkdir vuepress-element-doc && cd vuepress-element-doc
Copy the code
  1. Initialize NPM package management and set the package.jsonAdd scripts to
npm init -y
Copy the code
// package.json

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

Since we are going to do Element’s component documentation page, we will install Element here. If you need to showcase your own component library, you can simply install or import js and CSS from your own component library.

Create a page

The new home page.mdfile

The new docs/README. Md

---
home: trueheroImage: https://artice-code-1258339218.cos.ap-beijing.myqcloud.com/vuepress/element-index.png heroText: Consistency details: Consistent with the process and logic of real life, in accordance with the language and concepts used by users. Through the interface style and interaction effect, users can clearly perceive their own operations. The interface is simple and straightforward, allowing users to quickly identify rather than recall, reducing the burden of user memory. Footer: by hungry --### Design principles

<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="Consistency">
    <p style="margin:5px"<p style= "max-width: 100%; clear: both; min-height: 1em"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="Feedback">
    <p style="margin:5px"<p style= "max-width: 100%; clear: both; min-height: 1em"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="Efficiency">
    <p style="margin:5px"<p style= "max-width: 100%; clear: both; min-height: 1em"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="Controlled">
    <p style="margin:5px"Word-wrap: break-word! Important; "> <p style=" max-width: 100%"margin:0px; font-size: 12px; color:#666">Controllability</p>
  </div>
</div>
Copy the code

There are three syntax types in this readme.md:

  1. YAML: coping with---Wrapped around this is the Front Matter of the YAML syntax, which must be located.mdThe top is optional.
  2. Markdown: including### Design principlesPart of it is Markdown syntax, which I’m sure you’re familiar with.
  3. HTML: Finally, we are familiar with HTML syntax, as it is known, in.mdYou can use HTML syntax in.

Note: The image address in docs/ readme. md is the address placed on OSS because it is easier to use. You can also use local public files, see Vuepress/ Static Resources/Public Files.

Creating a Configuration File

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

module.exports = {
  theme: ' '.title: 'VuePress + Element'.description: 'VuePress builds Element library tutorial sample code '.base: '/'.port: '8080'.themeConfig: {},
  head: [].plugins: [].markdown: {}}Copy the code

Start the project

Run the VuePress command to view the result

npm run dev
Copy the code

Browser accesslocalhost:8080If there are no accidents, I believe you can already see the following effect on the page, which is our pageREADME.mdThe overall effect of YAML + Markdown + HTML written in this file.

Create a component page

Of the new component page.mdfile

Create /docs/comps/ readme. md and fill in the content. This is modeled after the Installation page on Element’s website.

# installation

# # NPM installationNPM is recommended for installation, which works better with the WebPack packaging tool. npm i element-ui -S## CDNYou can obtain the latest version of resources from unpkg.com/element-ui. You can use them by importing JS and CSS files to the page. <! -- Introducing styles --><link rel="stylesheet" href="https://unpkg.com/element-ui/lib/theme-chalk/index.css"><! -- Introducing a component library --><script src="https://unpkg.com/element-ui/lib/index.js"></script>

Copy the code

Create /docs/comps/select.md and fill it in. The two files were created so that we could later set up the document sidebar, which mimics the selector component page on Element’s website.

# Select selectorWhen there are too many options, use the drop-down menu to display and select the content.## Basic usageApplicable to a wide range of basic radio optionsCopy the code

Configure the top navigation bar

In the/docs /. Vuepress/config. Js configuration in the top navigation bar configuration field themeConfig. Nav. The code is as follows:

module.exports = {
  theme: ' '.title: 'VuePress + Element'.description: 'VuePress builds Element library tutorial sample code '.base: '/'.port: '8080'.themeConfig: { // Add new code
    nav: [ // Configure the top navigation bar
      {
        text: 'home'.link: '/'
      },
      {
        text: 'components'.link: '/comps/'}},head: [].plugins: [].markdown: {}}Copy the code

Configure the sidebar of the component page document

In the/docs /. Vuepress/config. Js configuration in the top navigation bar configuration field themeConfig. The sidebar. The code is as follows:

module.exports = {
  theme: ' '.title: 'VuePress + Element'.description: 'VuePress builds Element library tutorial sample code '.base: '/'.port: '8080'.themeConfig: {
    nav: [{text: 'home'.link: '/'
      },
      {
        text: 'components'.link: '/comps/'}].sidebar: { // Configure the sidebar section
      '/comps/': ['/comps/'.'/comps/select.md']}},head: [].plugins: [].markdown: {}}Copy the code

At this point I’m sure you’ll be able to see a page like this in your browser that smells a little like an Element document.

Component display effect realization

So far, however, we have not introduced Element’s component parts. Since it is a component library, we naturally want to implement something like Element, with the component display above and the sample code below. So let’s see how we can do that, okay

Installing the Demo Plug-in

We will use a vuepress-plugin-demo-container plug-in. Use the following command to install it

npm install vuepress-plugin-demo-container
Copy the code

Then in the/docs /. Vuepress/config. Js files are configured in the plug-in

module.exports = {
  // ...
  plugins: ['demo-container'], // Configure markdown: {}}Copy the code

knowenhanceApp.js

Have you ever thought that when we use Element in our projects, we need to introduce Element in app.js and call vue. use(Element) to use Element components in Vue? If we want to use Element in VuePress, Where do we need to write this code?

At this point, we need to recognize a new file, enhanceapp.js, which is the second most important file in VuePress after config.js. When you want to do some Vue application level configuration, you need to configure it in this file. Let us create the file in the/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)
  }
}
Copy the code

Introducing Element components

Let’s try using Element in the /docs/comps/select.md file we just created. Replace the original content with the following.

# Select selectorWhen there are too many options, use the drop-down menu to display and select the content.## Basic usageApplicable to a wide range of basic radio options ::: Demo Applies to a wide range of basic radio optionsHTML 
       (Note: you need to remove the '\'!!) : : :Copy the code

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

Deploy VuePress

At this point, the basic framework of the component library is built, and all that is left is to populate it and deploy it. Now let’s talk about deployment.

Executing deployment Commands

Remember when we configured the “build” of the VuePress deployment script in package.json earlier: “VuePress build docs”? So we just need to execute the following command

npm run build
Copy the code

If you look at the file, you will see that /docs/.vuepress/dist is now added, and the dist directory is our final deployment directory.

├ ─ ─ docs │ ├ ─ ─. Vuepress │ │ ├ ─ ─ config. Js │ │ ├ ─ ─ dist │ │ │ ├ ─ ─ 404 HTML │ │ │ ├ ─ ─ assets │ │ │ │ ├ ─ ─ CSS │ │ │ │ │ └ ─ ─ 0. Styles. 262 ade0c. CSS │ │ │ │ ├ ─ ─ fonts │ │ │ │ │ ├ ─ ─ element - the ICONS. 535877 f5. Woff │ │ │ │ │ └ ─ ─ Element - the ICONS. 732389 DE. The vera.ttf │ │ │ │ ├ ─ ─ img │ │ │ │ │ └ ─ ─ search. 83621669. The SVG │ │ │ │ └ ─ ─ js │ │ │ │ ├ ─ ─ 2. Ae254118. Js │ │ │ │ ├ ─ ─ 3. C4b624da. Js │ │ │ │ ├ ─ ─ 4.8 c48097d. Js │ │ │ │ ├ ─ ─ 5. A4fed9a4. Js │ │ │ │ ├ ─ ─ 6. Efea7d5a. Js │ │ │ │ ├ ─ ─ 7. Fc05164e. Js │ │ │ │ ├ ─ ─ 8.8 ee7961b. Js │ │ │ │ ├ ─ ─ 9. E8d922fc. Js │ │ │ │ └ ─ ─ app. 90733 c82. Js │ │ │ ├ ─ ─ comps │ │ │ │ ├ ─ ─ index. The HTML │ │ │ │ └ ─ ─ the select. The HTML │ │ │ └ ─ ─ index. The HTML │ │ └ ─ ─ enhanceApp. Js │ ├ ─ ─ the README. Md │ └ ─ ─ comps │ ├ ─ ─ README. Md │ └ ─ ─ the select. The md ├ ─ ─ package - lock. Json └ ─ ─ package. The jsonCopy the code

Deploy using the Web Server

Just point the root directory at /docs/.vuepress/dist/ to deploy to the service. Here we use Apache on native MAMP as the Web Server. Of course, you can use Nginx or any server of your choice to deploy.

Enter the port name configured for the Web Server and you will see that the deployment is successful

The resources

  1. VuePress official document
  2. DemoContainer plug-in

The source address

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