How to build component library documents

Preface

When we finish developing a component library , You need a component description document , The document page is the most direct window for obtaining information . Document pages generally contain this information ：

• Description of the component
• Components Demo Demonstration of examples 、 Description and source code
• Parameter document of the component

Component documentation is the key to letting others know about the component library , Including the scope of application of component library （pc End , Mobile , Lightweight or heavyweight ）, Compatible browser version , Design principles and background , And community ecology , Usage, etc .

About how to develop component libraries , Look at this ：

heaven-ui

Document generation

It's recommended here vuepress , Can help us quickly complete the construction of component library documents .(vuepress.vuejs.org/zh/guide/)

vuepress Is a document generation tool , Default style and vue The official documents are almost identical , Because it was created for vue Document support with related subprojects . It has... Built in Markdown An extension of , It's used when writing documents markdown To write , The most worry is that you can directly in Markdown Use... In the document Vue Components , It means that every component written in our component library , It can be used directly in the document , Show the actual running effect of the component . My case website is through vuepress To write it , After generating a static website , use gh-pages Deploy directly to github On , It can also be deployed directly to our own website .

vuepress Better yet, you can customize it webpack Configuration and themes , It means that you can make your own document site have more functional features during the development phase , At the same time, you can change the site style to your own theme style . There's no need for us to start over , For the requirement that we want to quickly complete the document construction of component library , It's still quite effective .

VuePress Building documents

VuePress yes Vue Static website generator driven . Support in Markdown Use in Vue Components , concise , High performance . Of course, you can also use other document generators , Such as Docz、Storybook etc. .

You can learn how to use... According to the official documents ：www.vuepress.cn/guide/getti…

Project generation and configuration

install

You can right-click to manually create , You can also use mkdir Command NEW ：

mkdir heavenUi && cd heavenUi
 Copy code 

Global installation VuePress

npm install -g vuepress
 Copy code 

Get into vuepressBlogDemo Folder , Initialize project

Use npm init or npm init -y（ Default yes）

npm init -y
 Copy code 

To configure scripts

package.json

{ 
     "docs:dev": "vuepress dev docs", 
     "docs:build": "vuepress build docs" 
}
 Copy code 

initialization docs

Create directories and files as shown in the following figure

VuePress follow “ Convention over configuration ” Principles , The recommended directory structure is as follows ：

.
├── docs
│   ├── .vuepress ( Optional )
│   │   ├── components ( Optional )
│   │   ├── theme ( Optional )
│   │   │   └── Layout.vue
│   │   ├── public ( Optional )
│   │   ├── styles ( Optional )
│   │   │   ├── index.styl
│   │   │   └── palette.styl
│   │   ├── templates ( Optional ,  Be careful with your configuration )
│   │   │   ├── dev.html
│   │   │   └── ssr.html
│   │   ├── config.js ( Optional )
│   │   └── enhanceApp.js ( Optional )
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json
 Copy code 

Be careful

Please note the capitalization of the directory name .

• docs/.vuepress: For storing global configuration 、 Components 、 Static resources, etc .

1. docs/.vuepress/components: In this catalog Vue Components will be automatically registered as global components .
2. docs/.vuepress/theme: For storing local themes .
3. docs/.vuepress/styles: Used to store style related documents .
4. docs/.vuepress/styles/index.styl: Global style files that will be automatically applied , Will be generated in the final CSS End of file , Has a higher priority than the default style .
5. docs/.vuepress/styles/palette.styl: Used to override the default color constant , Or set up a new stylus Color constant .
6. docs/.vuepress/public: Static resource directory .
7. docs/.vuepress/templates: Storage HTML Template file .
8. docs/.vuepress/templates/dev.html: For the development environment HTML Template file .
9. docs/.vuepress/templates/ssr.html: Build on Vue SSR Of HTML Template file .
10. docs/.vuepress/config.js: The entry file for the configuration file , It can also be YML or toml.
11. docs/.vuepress/enhanceApp.js: Client application enhancements .

Home page information settings

---
home: true
actionText:  Start using 
#  Website portal   Configure the path according to your home page 
actionLink: /component/installation
features:
- title: heaven-UI
  details:  A set of based on  Vue.js  The high quality of UI  Component library 
footer: MIT Licensed | COPYRIGHT 
---
 Copy code 

The effect of the home page is as follows

Configure navigation

module.exports = {
  title: 'Heaven', //  Set site title 
  description: ' Light weight 、 reliable  Vue  Component library ', //  describe 
  dest: './dist', //  Set output directory 
  themeConfig: { //  Theme configuration 
    nav: [ //  Head navigation bar 
      {
        text: ' Home page ',
        link: '/'
      },
      {
        text: " Components ",
        link: "/component/installation",
      },
    ],
    //  Add sidebar for the following routes 
    sidebar: {
      '/components/': [
        {
          title: ' Components ',
          collapsable: false,
          children: [
            'button',
            // ...  Other components 
          ]  
        },
        //  Other settings 
      ]
    }
  }
}
 Copy code 

Enhancement files for client applications

enhanceApp.js

This file is used to add components Demo Show the optimized configuration

install

npm install heaven-ui less less-loader --save
 Copy code 

If local debugging is required , can link Developed component library heaven-ui

npm link heaven-ui
 Copy code 

.vuepress/enhanceApp.js

/**
 *  Expand  VuePress  application 
 */
import Heaven from 'heaven-ui'
import 'heaven-ui/lib/heaven-ui.min.css'
 
export default ({
 Vue, // VuePress  In use  Vue  Constructors 
 options, //  Some options attached to the root instance 
 router, //  Routing instance of current application 
 siteData //  Site metadata 
}) => {
 // ... Do some other application level optimizations 
 Vue.use(Heaven)
}
 Copy code 

.vuepress/components/button.vue Files can be button Component's Demo Display style

stay md Added in document You can render directly button.vue The content of

<template>
  <div>
    <h-button> Default button </h-button>
    <h-button type="primary"> Main buttons </h-button>
    <h-button type="success"> Success button </h-button>
    <h-button type="warning"> Warning button </h-button>
    <h-button type="danger"> Danger button </h-button>
    <h-button type="info"> Information buttons </h-button>   
  </div>
</template>

<script>
export default {
}
</script>

<style>
</style>
 Copy code 

Write the corresponding component Markdown file

#### Button  Button 

####  Common operation button .
<ClientOnly>
<button></button>
</ClientOnly>

``` html
<template>
   <h-button> Default button </h-button>
   <h-button type="primary"> Main buttons </h-button>
   <h-button type="success"> Success button </h-button>
   <h-button type="warning"> Warning button </h-button>
   <h-button type="danger"> Danger button </h-button>
   <h-button type="info"> Information buttons </h-button>
</template>
```
 Copy code 

The effect is as follows

visit http://localhost:8080 You can see the document . Of course , You can deploy documents to your own server , It can also be deployed to Github pages On .

Summary

thus , The documentation of the component library is set up , You can supplement the documents later .

Component library address

Warehouse address

Document presentation address