ninebot-docs

Appearance

文档编写指南 ​

项目地址 ​

如果没有权限请联系任鹏(peng.ren@ninebot.com).

node 版本 ​

node >= 18

项目的安装及运行 ​

依赖安装 npm install

项目运行 npm run docs:dev

分支管理 ​

master:主分支,用于打 tag;

release:发布分支,用于上线;

流程:从 release 拉取开发分支进行开发,开发完成提 MR 合并开发分支到 release上线;上线成功之后,将 release 分支合并到 master并打 tag;

NOTE

1.提 MR 之前需要先将 release 分支合并到当前的开发分支;
2.MR 提给任鹏(peng.ren@ninebot.com);

头部导航及菜单设置 ​

本平台基于 vitepress 搭建，头部导航及菜单设置参考vitepress。

文件结构 ​

每个组件/工具库都有一个单独的文件夹,文件夹下包含一个 index.md 文件(SDK 的依赖版本及安装命令等)及多个组件文件夹;

bash
├── docs
│   ├── h5Components
│   │   ├── index.md
│   │   ├── NBLogin
│   │   │   ├── index.md
│   │   │   ├── demo
│   │   │   │   ├── index.vue
│   │   ├── NBDialog
│   ├── pcComponents
│   │   ├── index.md
│   │   ├── xxxx

NOTE

如果 SDK 非常简单,组件库的文件下可以只存在一个 index.md 文件.

引入组件库 ​

本文档在编写时不可避免的会需要引入其他的组件库,比如element-plus、vant等,由于 vitepress 工程没有 main.ts 文件, 所以需要在 .vitepress/theme/index.js 中引入组件库;

表格编写技巧 ​

表格在 markdown 语法中编写比较复杂,可以通过Typora工具简化编辑过程;

状态标识符 ​

在编写文档时,需要根据组件当前所处的状态进行标识,如当前组件正处于测试阶段,那么需要在菜单中使用 Test 标示符号进行标注;当组件测试通过后,需要将 Test 标示符号去掉;

json
sidebar: {
    '/docs/h5Components/':[
        {
            text: 'h5组件库',
            items:[
                { text: '介绍', link: '/docs/h5Components/' },
                { text: 'NBDialog <span class="slider-badge">Test</span>', link: '/docs/h5Components/NBDialog/' }, 
                { text: 'NBLogin <span class="slider-badge">Test</span>', link: '/docs/h5Components/NBLogin/' }, 
            ]
        }
    ],
    '/docs/pcComponents/':[
        {
            text: 'pc组件库',
            items:[
                { text: '介绍', link: '/docs/pcComponents/' },
            ]
        }
    ]
}

WARNING

标识符极其重要,一定不能忘记修改!!!!! 否则会对用户造成困扰;