shotCat_doc

Introduction

---

shotCat_doc peut vous aider à créer rapidement votre propre document de bibliothèque de composants, basé sur vuepress. Il imite le document element-ui et implémente l'affichage des composants, l'affichage du code, le fonctionnement en ligne, l'affichage de la table API, le changement de version du document, la prise en charge des commentaires, etc. Il peut vous aider à créer rapidement un prototype de document de composant à partir de zéro. Il a déjà effectué tout le travail de configuration dont vous avez besoin par défaut, ce qui le rend véritablement utilisable dès le départ.

Si vous aimez ce projet, bienvenue dans la star ! Ou si vous avez des problèmes d'utilisation ou des bugs, veuillez soumettre des problèmes et des PR.

• Adresse GitHub
• Adresse de démonstration
• Adresse de mon blog personnel : shotcat.com
• Mon compte Nuggets

Installer

Projet de clonage
git clone https://github.com/1011cat/shotCat_doc.git

Entrez le répertoire du projet
cd shotCat_doc

Installer les dépendances
npm install

Il est recommandé de ne pas utiliser cnpm pour installer directement les dépendances, car il y aura divers bugs étranges. Vous pouvez résoudre le problème de la vitesse de téléchargement lente de NPM en procédant comme suit
npm install --registry=https://registry.npm.taobao.org

Démarrer le service
npm run dev

Accès au navigateur http://localhost:6868

Description du répertoire de la structure du projet

 |-- shotCat_doc
    |-- LICENSE
    |-- deploy.sh   //用于自动部署
    |-- package-lock.json
    |-- package.json
    |-- docs
    |   |-- README.md   //文档首页配置
    |   |-- .vuepress   //用于存放全局的配置、组件、静态资源等。
    |   |   |-- config.js   //文档配置文件
    |   |   |-- enhanceApp.js   //应用级别的配置 其实就是引入文档需要用到的第三方插件
    |   |   |-- components  //该目录中的 Vue 组件将会被自动注册为全局组件
    |   |   |   |-- baseComponent   //文档会用到的全局公共组件
    |   |   |   |   |-- apiTable.vue    //组件的参数表格
    |   |   |   |   |-- codeBox.vue     //包裹示例的组件
    |   |   |   |   |-- star.vue    //底部彩蛋组件
    |   |   |   |-- demo   //组件示例 
    |   |   |       |-- catButton   //存放button组件相关示例
    |   |   |           |-- type_catButton.vue
    |   |   |-- dist    //存放打包后的文件
    |   |   |   
    |   |   |-- public  //静态资源目录
    |   |   |   |-- favicon.jpeg
    |   |   |   |-- name.png
    |   |   |-- styles  //用于存放样式相关的文件
    |   |       |-- index.styl  //将会被自动应用的全局样式文件，会生成在最终的 CSS 文件结尾，具有比默认样式更高的优先级
    |   |       |-- palette.styl    //用于重写默认颜色常量，或者设置新的 stylus 颜色常量
    |   |-- components  //存放组件文档要用到的markdown
    |   |   |-- README.md
    |   |   |-- 1.0 //1.0 版本的文档 如果不需要版本管理，直接删除1.0这层文件夹即可
    |   |   |   |-- README.md
    |   |   |   |-- catButton.md
    |   |   |-- 2.0 //2.0 版本的文档
    |   |       |-- README.md
    |   |       |-- catButton.md
    |   |-- guide   //使用说明的文件夹
    |       |-- introduction.md
    |       |-- quickStart.md
    |-- src //存放你自己的ui组件库
        |-- index.js
        |-- components
            |-- catButton
                |-- catButton.vue

démarrage rapide

étape 1

Placez votre propre bibliothèque de composants dans le répertoire racine, puis configurez-la dans docs/.vuepress/enhanceApp.js

 //docs/.vuepress/enhanceApp.js

//引入你的组件库 确保你的组件库index文件有install方法
//如果不会，没关系，src目录里自带一个简单组件库示例，可供参考
import Cat from '../../src/index'

export default ( {
    Vue , // VuePress 正在使用的 Vue 构造函数
    options , // 附加到根实例的一些选项
    router , // 当前应用的路由实例
    siteData // 站点元数据
  } ) => {
    Vue . use ( Cat )    
  }

Configurez ensuite le chemin de votre barre latérale Pour une configuration détaillée, vous pouvez directement afficher les commentaires dans docs/.vuepress/components/config.js.

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

//这里配置的是button组件页面的路径
sidebar : {
    '/components/2.0/' : [
        {
            title : '基础组件' ,   // 必要的 配置侧边栏名称
            path : '' , 
            collapsable : false , // 可选的, 右侧侧边栏是否展开,默认值是 true
            // 如果组件很多时，建议将children配置单独放到一个js文件中，然后进行引入
            children : [
                {
                    title : 'Button 按钮' ,
                    path : 'catButton' , //在项目中对应的路径是 docs/components/2.0/catButton.md
                } ]
        }
    ]
} ,

étape 2

Vous pouvez maintenant commencer à écrire votre propre documentation de composant. Voici un exemple d'affichage de composant : prenez mon bouton chat comme exemple.

// docs/.vuepress/components/demo/catButton.vue

< template >
    <!-- 注意这段代码会放入slot里，所以必须再包裹一层div，否则会解析报错 -->
    < 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 >

étape 3

Créez un fichier de démarque dans docs/components/2.0/catButton.md dans le chemin configuré ci-dessus. Ensuite, vous pouvez volontiers écrire des pages de composants de boutons !

// docs/components/2.0/catButton.md

---
title: 2.0 Button 按钮
---

<!-- baseComponent-codeBox 组件即为.vuepress/components/baseComponent/codeBox文件，vuepress会默认把它解析为`baseComponent-codeBox`组件，这里我们如下对代码进行包裹，具体功能可以查看codeBox注释和页面效果 -->
< baseComponent-codeBox title ="按钮类型" description ="按钮类型通过设置type为primary、success、info、warning、danger、text创建不同样式的按钮，不设置为默认样式。 " onlineLink =" https://codepen.io/1011cat/pen/KjEOWO " >

    <!-- 同理demo-catButton-type_catButton即为我们step2编写的示例组件 -->
  < demo-catButton-type _catButton > </ demo-catButton-type _catButton >

    <!-- 这里highlight-code为引入的第三方代码高亮组件，里面包裹的就是上面示例组件的代码 -->
  < 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 >

<!-- 组件的参数表格,这里我没有使用自带的markdown表格，因为太丑，样式不好修改，有时参数描述较少时，不能自动撑满一行，所以自己写了一个组件；titile为表格标题，tableHead为表头，tableBody为具体参数设置，并且支持el-table的table参数 -->
< baseComponent-apiTable
  title =" Table Attributes "
  :tableHead = " tableHead "
  :tableBody = " tableBody " >
</ baseComponent-apiTable >

<!-- Vssue为引入的评论插件 -->
< Vssue title =" Vssue Demo " />

<!-- 其实在vuepress里的每个.md其实和.vue很像的，你基本可以按照vue组件模式来写 -->
< script >
    // 基本上和写vue一样
  export default {
    data ( ) {
      return {
          //表头为字符串，写法和md一样，中间以`|`间隔就行
        tableHead : `参数 | 说明 | 类型 | 可选值 | 默认值` ,
            //表格为数组，其中每一项为字符串，代表每一行要展示的数据，写法也和md一样，中间以`|`间隔就行
        tableBody : [
          `size | 尺寸 | String | medium / small / mini | —` ,
          `type |	类型 | string |	primary / success / warning / danger / info / text | —`
        ] ,
      }
    } ,

  }
</ script >

<!-- 和vue一样，也可以设置样式，并且这里style样式只对当前md有效，不需要加上scoped -->
< style >

</ style >

À ce stade, vous avez réalisé un simple affichage de composant de bouton. En résumé, c'est :

1. Configurer la navigation dans la barre latérale
2. Écrire un exemple de code
3. Page correspondante md

Une configuration et des instructions plus détaillées se trouvent dans le code correspondant. Chaque fichier de code contient des commentaires ligne par ligne et des instructions de prévention des pièges.