Introduction to the

I recently took over the company’s public UI component library, and came up with the idea of creating a component library document like element’s official website.

ShotCat_doc helps you quickly build your own component library documentation, which is based on vuepress. Modeled after the Element-UI document, realize component display, code display, online operation, API table display, document version switch, support comments and so on. It helps you quickly prototype component documentation from zero, and it does all the configuration work you need by default, right out of the box.

If you like this project welcomestar!Or any usage problems and bugs, welcome to mentionIssue and pr

  • Making the address
  • Demo address
  • My personal blog is shotcat.com

The installation

Clone git clone https://github.com/1011cat/shotCat_doc.git project

Go to the project directory CD shotCat_doc

The installation depends on NPM install

Do not directly use CNPM to install dependencies, there will be a variety of weird bugs. Can be solved through the following NPM slow download speed of NPM install – registry=https://registry.npm.taobao.org

Start the service NPM run dev

Browser visit http://localhost:6868

Project structure directory description

| - shotCat_doc | - LICENSE | -- deploy. Sh / / used to automatically deploy | -- package - lock. Json | -- package. Json | - docs | | - README. Md . / / the document page configuration | | - vuepress / / to hold global static resource configuration, components, etc. | | | -- config. Js / / document profile | | | -- enhanceApp. Js / / application level configuration Is to introduce the document need to use third-party plugins | | | - components / / in the directory Vue Component will automatically be registered as a global components | | | | - baseComponent / / document will use the global common components of | | | | | -- apiTable. Vue / / component parameter table | | | | | -- codeBox. Vue / / package sample components | | | | | -- star. Vue / / at the bottom of the egg component | | | | - demon / / component sample | | | | - catButton/store/button component related sample | | | | - Type_catButton. Vue | | | - dist / / for packing after the file | | | | | | - public / / static resource directory | | | | -- the favicon. Jpeg | | | | -- the name. PNG | | | - styles / / to hold style files related | | | -- index. Styl / / will automatically be applied global style file, will be generated at the end of the final CSS file, Has a higher priority than the default styles | | | -- the palette. Styl / / used to override the default color constant, Or set a new stylus color constant | | - components / / storage component documentation required for the markdown | | | -- README. Md | | | - 1.0 / / 1.0 version of the document If you don't need version management, Directly to delete this folder can be 1.0 | | | | -- README. Md | | | | -- catButton. Md | | | - 2.0 / / 2.0 version of the document | | | -- README. Md | | | -- catButton. Md | | - guide / / instructions folder | | - the introduction. The md | | -- quickStart. | - SRC / / md to store your own UI component library | -- index. Js | - components | - catButton |-- catButton.vueCopy the code

Quick start

step1

Put your component library in the root directory, then the docs /. Vuepress/enhanceApp js configured

//docs/.vuepress/enhanceApp.js

// Import your library. Make sure your library index file has the install method
// If not, there is a simple component library example in the SRC directory for your reference
import Cat from '.. /.. /src/index'

export default ({
    Vue, // VuePress is using the Vue constructor
    options, // Some options to attach to the root instance
    router, // Route instance of the current application
    siteData // Site metadata
  }) => {
    Vue.use(Cat)    
  }
Copy the code

Then configure your sidebar path, detailed configuration can be directly to check the docs /. Vuepress/components/config. The annotation in the js.

// docs/.vuepress/components/config.js

// This is the path of the Button component page
sidebar:{
    '/ components / 2.0 /':[
        {
            title: 'Base components'.// The required configuration sidebar name
            path: ' '.collapsable: false.// Optional whether to expand the right sidebar, the default is true
            // If there are many components, it is recommended to put the children configuration in a separate JS file and import it
            children: [
                {
                    title:'Button Button'.path: 'catButton'./ / in the project the corresponding path is 2.0 / catButton docs/components/md}}}]],Copy the code

step2

Now that you’re ready to document your own components, here’s a component demonstration example: take my Cat-Button

// docs/.vuepress/components/demon/catButton.vue

<template>
    <! -- Notice that this code will be placed in the slot, so you must wrap the div layer, otherwise it will parse an error -->
    <div>
        <cat-button text="default"></cat-button>
        <cat-button text="primary" type="primary"></cat-button>
        <cat-button text="success" type="success"></cat-button>
        <cat-button text="info" type="info"></cat-button>
        <cat-button text="warning" type="warning"></cat-button>
        <cat-button text="danger" type="danger"></cat-button>
        <cat-button text="text" type="text"></cat-button>
    </div>
</template>

<script>
    export default{}</script>

Copy the code

step3

Docs in the configured above path/components / 2.0 / catButton md, creating markdown files. Then you can have fun writing button component pages!

/ / docs/components / 2.0 / catButton md - title: 2.0 - Button Button<! - baseComponent - codeBox component is. Vuepress/components/baseComponent/codeBox file, vuepress will default to parse it as ` baseComponent - codeBox ` components, Here we wrap the code as follows. For details, see codeBox comments and page effects -->
<baseComponent-codeBox title="Button type" description="Button type Create different styles of buttons by setting type to primary, success, info, warning, Danger, text, not default." onlineLink="https://codepen.io/1011cat/pen/KjEOWO">

    <! -- Demon-catbutton-type_catbutton -->
  <demon-catButton-type_catButton></demon-catButton-type_catButton>

    <! Highlight-code: highlights the component with imported third-party code, which wraps the code for the sample component above.
  <highlight-code slot="codeText" lang="vue">
    <template>
      <div>
        <cat-button text="default"></cat-button>
        <cat-button text="primary" type="primary"></cat-button>
        <cat-button text="success" type="success"></cat-button>
        <cat-button text="info" type="info"></cat-button>
        <cat-button text="warning" type="warning"></cat-button>
        <cat-button text="danger" type="danger"></cat-button>
        <cat-button text="text" type="text"></cat-button>
      </div>
    </template>
    <script>
        export default{}</script>
  </highlight-code>
</baseComponent-codeBox>

<! -- Component parameter table, here I did not use the markdown table, because it is too ugly, the style is not easy to modify, sometimes when the parameter description is small, it cannot automatically fill a line, so I wrote a component; Titile is the table title, tableHead is the table header, tableBody is the specific parameter setting, and supports the table parameter of el-table -->
<baseComponent-apiTable
  title="Table Attributes"
  :tableHead = "tableHead"
  :tableBody = "tableBody">
</baseComponent-apiTable>

<! -- Vssue for the introduction of the comment plugin -->
<Vssue title="Vssue Demo" />

<! -- In fact, every.md in Vuepress is similar to.vue, you can basically write it in vue component mode -->
<script>
    // Basically the same as writing vue
  export default {
    data() {
      return {
          / / header as a string, writing and md, among with ` | ` interval
        tableHead:Types of ` parameters | | | | defaults ` optional values./ / headers for arrays, each item as a string, on behalf of each line to show the data, writing and md, middle to ` | ` interval
        tableBody: [
          `size | 尺寸 | String | medium / small / mini | —`.` type | | type string | primary/success/warning/danger/info/text | - `,}}}</script>

<! Just like vue, you can set styles, and the style style is only valid for the current MD, no need to add scoped -->
<style>

</style>

Copy the code

At this point, you have a simple button component presentation that can be summarized as follows:

  1. Configure sidebar navigation
  2. Write sample code
  3. Corresponding page MD

More detailed configuration and instructions are in the corresponding code. In each code file, there are line – by – line comments and anti – pit instructions.

If you like this project welcomestar!Or any usage problems and bugs, welcome to mentionIssue and pr

  • Making the address
  • Demo address
  • My personal blog is shotcat.com