preface

When we develop a component library, we need to have a component description document, the document page is the most direct window to obtain information. The document page usually contains this information:

  • Component Description
  • Component Demo sample presentation, description and source code
  • Parameter documentation for the component

Component documentation is a key step in letting others know the scope of the component library (PC, mobile, lightweight or heavyweight), compatible browser versions, design principles and background, community ecology, usage, etc.

For information on how to develop a component library, see this article:

heaven-ui

Document generation

Vuepress is recommended as a quick way to build a component library document. (vuepress.vuejs.org/zh/guide/)

Vuepress is a document generation tool. The default style is almost identical to vUE official documentation, as it was created to support documentation for VUE and related sub-projects. Markdown has a built-in extension for Markdown, which allows you to write documents using Markdown. The most convenient part is that you can use Vue components directly in Markdown files, which means that components written in our component library can be directly used in documentation to show how the components actually work. My case website is also written through Vuepress. After generating a static website, gh-Pages can be directly deployed on Github or our own website.

The nice thing about Vuepress is that you can customize the WebPack configuration and theme, which means you can make your documentation site more feature-rich at development time and change the site style to your own theme style. This saves us from having to go back to the drawing board and works well for our need to quickly document our component library.

VuePress builds documents

VuePress is a VUUe-powered static web site generator. Support the use of Vue components in Markdown for simplicity and high performance. Of course, you can also use other document generators such as Docz, Storybook, etc.

According to the official documentation to learn how to use: www.vuepress.cn/guide/getti…

Project generation and configuration

The installation

You can right-click to create a new file or run the mkdir command to create a new file:

mkdir heavenUi && cd heavenUi
Copy the code

Install VuePress globally

npm install -g vuepress
Copy the code

Go to the vuepressBlogDemo folder and initialize the project

Use NPM init or NPM init -y (default yes)

npm init -y
Copy the code

The configuration scripts

package.json

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

Initialize the docs

Create directories and files as shown in the following figure

VuePress follows the principle of convention over configuration. The recommended directory structure is as follows:

. ├ ─ ─ docs │ ├ ─ ─ the vuepress (optional) │ │ ├ ─ ─ components (optional) │ │ ├ ─ ─ the theme (optional) │ │ │ └ ─ ─ Layout. The vue │ │ ├ ─ ─ public (optional) │ │ ├ ─ ─ styles (optional) │ │ │ ├ ─ ─ but styl │ │ │ └ ─ ─ the palette. Styl │ │ ├ ─ ─ templates (optional, Careful configuration) │ │ │ ├ ─ ─ dev. HTML │ │ │ └ ─ ─ SSR. HTML │ │ ├ ─ ─ the config, js (optional) │ │ └ ─ ─ enhanceApp. Js (optional) │ │ │ ├ ─ ─ the README. │ md ├ ─ ─ guide │ │ └ ─ ─ the README. Md │ └ ─ ─ config. The md │ └ ─ ─ package. The jsonCopy the code

Pay attention to

Please note the capitalization of the directory name.

  • Docs /. Vuepress: Stores global configurations, components, and static resources.
  1. Docs /. Vuepress/components: the directory of Vue components will automatically be registered as a global component.
  2. Docs /. Vuepress /theme: Stores local themes.
  3. Docs /.vuepress/styles: Stores style-related files.
  4. Docs /. Vuepress/styles/index. Styl: the global style file will be automatically applied, will be generated at the end of the final CSS file, with a higher priority than the default styles.
  5. Docs /. Vuepress/styles/palette. Styl: used to override the default color constant, or setting up the new stylus color constants.
  6. Docs /.vuepress/public: static resource directory.
  7. Docs /. Vuepress/templates: store HTML template file.
  8. Docs /. Vuepress/templates/dev. HTML: HTML template files used in the development environment.
  9. Docs /. Vuepress/templates/SSR. HTML: build time based on Vue SSR HTML template file.
  10. Docs /. Vuepress/config. Js: configuration file entry, can also be YML or toml.
  11. Docs /. Vuepress/enhanceApp. Js: enhance the client applications.

Home Page Information Settings

-- Home: true actionText: start using actionLink: / Component/Installation features: - title: Heaven - UI details: a set of Vue. Based the high quality of js UI component library footer: MIT Licensed | COPYRIGHT © -Copy the code

The home page effect is as follows

Configuration navigation

Module. exports = {title: 'Heaven', // set url description: 'Vue component library ', // '. / dist, / / set the output directory themeConfig: {/ / the topic configuration nav: [/ / navigation bar head {text: 'home page, link:'/'}, {the text: "component", the link: "/ Component /installation",},], // Add sidebar sidebar: {'/components/': [{title: 'component ', collapsable: False, children: [' button ', / /... other components]}, / / other Settings]}}}Copy the code

An enhancement file for the client application

enhanceApp.js

This file is used to add the optimized configuration shown in the component Demo

The installation

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

For local debugging, link’s component library, heaven- UI, is available

npm link heaven-ui
Copy the code

.vuepress/enhanceApp.js

/** * import Heaven from 'Heaven - UI' import 'Heaven - UI /lib/ Heaven - UI. // VuePress is using Vue constructor options, // some options attached to the root instance router, // currently applied routing instance siteData // site metadata}) => {//... Use (Heaven)}Copy the code

. Vuepress/components/button. Vue file can be the style of the button component Demo show

Add to the MD file to render button.vue directly

<template> <div> < H-button > Default button </h-button> < H-button type="primary"> Primary button </ H-button > < H-button Type ="success"> <h-button > < H-button type="warning"> <h-button > <h-button type="danger"> <h-button type="info"> </h-button> </div> </template> <script> export default {} </script> <style> </style>Copy the code

Write Markdown files for the corresponding components

#### Button #### Common operation Button. <ClientOnly> <button></button> </ClientOnly> HTML <template> <h-button> default button </h-button> <h-button <h-button > < H-button type="success"> < H-button type="warning"> <h-button type="danger"> <h-button type="info"> </h-button> </templateCopy the code

Results the following

Visit http://localhost:8080 to see the documentation. Of course, you can deploy documents on your own server or on Github Pages.

summary

At this point, the description of the component library documentation is completed, the follow-up to supplement the documentation can be.

Component library address

The warehouse address

Document presentation address