docsify学习笔记(二)2019-05-25

小小的改变,大大的化

基于docsify进行文档管理的内部分享

一、培训目的

通过近期与其他开发团队的沟通交流,发现他们对接口文档的管理思路比较先进、查阅方便等;因此,有必要学习借鉴其他开发团队的接口文档管理思路,通过研究发现他们使用的是docsify进行接口文档的管理,在业余时间对docsify进行了一个简单的研究,抽出一定的时间为大家做一个简单的内部分享,本次分享的主要目的如下:

(1)提升开发团队接口文档管理水平;
(2)方便团队与其他项目组的沟通、交流;
(3)提高接口文档的实用性、高效性;
(4)开发人员可以更加快速的查询等;

在正式分享前,我们先看一下以下几个接口查询效果,具体如下图所示:

docsify
微信小程序API
支付宝小程序
百度小程序

二、培训内容

2.1概况说明

本次培训,主要包含如下内容:

(1)docsify介绍及安装;
(2)MD文件基本语法介绍;
(3)文档管理demo演示;
(4)逐步掌握接口文档的编写;

2.2docsify介绍

2.2.1docsify介绍

docsify是一个文档生成工具,它直接加载 Markdown 文件并动态渲染,同时还可以生成封面页。 不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时 进行。 docsify是由现饿了么前端团队@elemeFE的cinwell.li编写的一套文档站点生成框架,github上 已有3k+ star,这款框架和其他框架如gitbook等相比,最大的区别就在于docsify不是静态生成html, 而通过动态请求markdown编译生成html。

2.2.2docsify特点

(1)无需构建无需编译,写完markdown文档直接发布
(2)容易使用并且轻量 (~18kB gzipped)
(3)智能的全文搜索
(4)提供多套主题
(5)丰富的 API
(6)支持 Emoji
(7)兼容 IE10+
(8)支持 SSR (example)
(9)快速上手

2.2.3文档规范的好处

(1)目录、说明清晰可见;
(2)便于开发人员预览查询;
(3)文档更加方便维护;

2.2.4官方网址

对于具体的学习资料,大家可以参考官方网站。

https://docsify.js.org/#/zh-cn/quickstart

2.2.5其它主流文档管理

目前市面上有大致这么几款主流的文档生成站点,分别为docsify、gitbook、Phenomic等,可帮助用户快速搭建文档站点。其它三种在此不再赘述,喜欢的人员可以自行了解;需要说明的是,目前微信相关的接口文档使用的是gitbook进行编写的。

2.3安装教程

2.3.1root安装

推荐安装 docsify-cli 工具,可以方便创建及本地预览文档网站。在安装docsify-cli之前需要确保您首先安装node。

npm i docsify-cli -g

2.3.2普通用户下初始化项目

如果想在项目的 ./docs 目录里写文档,直接通过 init 初始化项目。

docsify init ./docs

2.3.3开始写文档

初始化成功后,可以看到 ./docs 目录下创建的几个文件

-index.html 入口文件
-README.md 会做为主页内容渲染
-.nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件

直接编辑 docs/README.md 就能更新网站内容,当然也可以写多个页面。

2.3.4启动服务

运行一个本地服务器通过 docsify serve 命令可以方便的预览效果,而且提供 LiveReload 功能,可以实时的预览。默认访问 http://localhost:3000

docsify serve docs

如果需要启动其他端口,可以直接在后面增加-p 4000表示启动端口为4000

更多命令行工具用法,参考 docsify-cli 文档。

项目启动
预览效果

2.3.5手动初始化

如果不喜欢 npm 或者觉得安装工具太麻烦,我们其实只需要直接创建一个 index.html 文件。

index.html文件内容具体如下:

<!DOCTYPE html>
<html>
<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //...
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>

2.3.6侧边栏

为了有侧边栏,那么你可以创建你自己的_sidebar.md:

首先,你需要设置loadSidebar为true,详细信息可在配置段落中找到。

2.3.6.1 index.html配置如下所示:

<script> window.$docsify = { loadSidebar: true } </script> <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

2.3.6.2侧边栏md配置

创建_sidebar.md:

<!-- docs/_sidebar.md -->

- [Home](/) - [Guide](guide.md)

2.3.7完整demo示例

index.html详细配置示例如下所示:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">

  <!-- Theme: Simple -->
  <!--
  <link rel="stylesheet" href="https://unpkg.com/docsify-themeable/dist/css/theme-simple.css">
  -->
  <link rel="stylesheet" href="assets/theme-simple.css">

  <!-- Custom theme stylesheet -->
  <link rel="stylesheet" href="assets/theme-custom.css">


  <style>
        nav.app-nav li ul {
            min-width: 100px;
        }

  </style>
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      //定义路由别名,可以更自由的定义路由规则。 支持正则。
      alias: {
            '/.*/_sidebar.md': '/_sidebar.md'
      },
      // 加载 _sidebar.md,加载自定义侧边栏
      loadSidebar: true,
      //加载自定义导航栏
      loadNavbar: false,
      // 强制悬停,切换页面后是否自动跳转到页面顶部。
      auto2top: true,
      // 调整副标题的级数
      subMaxLevel: 2,
      // 替换主题色
      themeColor: '#4CAF50',
      themeable: {
          readyTransition : true, // default
          responsiveTables: true  // default
      },

      showLevel: true,
      //文档标题,会显示在侧边栏顶部。
      name: '',
      //配置仓库地址或者 username/repo 的字符串,会在页面右上角渲染一个 GitHub Corner 挂件。
      repo: '',
      //禁用 emoji 解析
      noEmoji: true,
      tocLevel: 6,
      //搜索配置项
      search: {
        maxAge: 86400000, // 过期时间,单位毫秒,默认一天
        paths: 'auto', // or 'auto'
        placeholder: '搜索',
        noData: '找不到结果',
        // 搜索标题的最大程级, 1 - 6
        depth: 4
      },
      pagination: {
        previousText: '上一章节',
        nextText: '下一章节',
      }

    }
  </script>

  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
  <script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>
  <script src="//unpkg.com/docsify-copy-code"></script>
  <script src="//unpkg.com/prismjs/components/prism-sql.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-http.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-json.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-bash.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-java.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-markdown.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-nginx.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-php.min.js"></script>
  <script src="//unpkg.com/prismjs/components/prism-python.min.js"></script>
  <script src="//unpkg.com/docsify-pagination/dist/docsify-pagination.min.js"></script>

  <!-- docsify-themeable -->
  <script src="https://unpkg.com/docsify-themeable"></script>


</body>
</html>

三、其它扩展

搭建公司内部文档管理平台,修改完毕后推送至远端自动刷新,考虑到时间问题,后续再做详细介绍。

3.1依赖环境

Docsify、GitLab、Jenkins 版本无要求

3.2运行环境

CentOS Linux release 7.3.1611

四、培训目标

通过本次内部培训,希望达成以下目标:

(1)对docsify文档管理有一定的了解和掌握;
(2)对MD文件的基本语法有一定的了解和掌握;
(3)开发人员后期定义接口规范逐步使用docsify的方式进行编写,文档实时自动刷新;
(4)对内部的接口文档管理等工作有一定的提高;

image7.png
image8.png
最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 216,001评论 6 498
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 92,210评论 3 392
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 161,874评论 0 351
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 58,001评论 1 291
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 67,022评论 6 388
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 51,005评论 1 295
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 39,929评论 3 416
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 38,742评论 0 271
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 45,193评论 1 309
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 37,427评论 2 331
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 39,583评论 1 346
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 35,305评论 5 342
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 40,911评论 3 325
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 31,564评论 0 21
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 32,731评论 1 268
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 47,581评论 2 368
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 44,478评论 2 352

推荐阅读更多精彩内容