docsify 安装配置文档

docsify 安装配置文档

安装运行环境npm

用sudo执行以下命令即可完成安装
node安装命令
$ sudo curl -sL -o /etc/yum.repos.d/khara-nodejs.repo https://copr.fedoraproject.org/coprs/khara/nodejs/repo/epel-7/khara-nodejs-epel-7.repo
npm安装命令
$ sudo yum install -y nodejs nodejs-npm
有了npm运行环境就可以快速开始docsify安装了
安装 docsify-cli 工具，可以方便创建及本地预览文档网站。
安装命令
sudo npm i docsify-cli -g

初始化项目

如果想在项目的 ./docs 目录里写文档，直接通过 init 初始化项目。
初始化命令：
sudo docsify init ./docs
执行完可以直接生成目录，以及index.html 入口文件，README.md 会做为主页内容渲染文件

本地预览网站

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

多页文档

结构如下：

-| docs/</br>
  -| README.md</br>
  -| guide.md</br>
  -| zh-cn/</br>
    -| README.md</br>
    -| guide.md</br>

对应访问路径如下：

docs/README.md        => http://domain.com</br>
docs/guide.md         => http://domain.com/guide</br>
docs/zh-cn/README.md  => http://domain.com/zh-cn/</br>
docs/zh-cn/guide.md   => http://domain.com/zh-cn/guide</br>

页面布局的创建：

除了初始化init时自动生成的index.html入口文件，和做为主页内容渲染README.md文件外，根据需要我们自行创建导航栏_navbar.md文件，侧边栏_sidebar.md文件
封面_coverpage.md文件，以及存放图片的_media文件等。这些文件在入口文件index.html中配置了相应的类型参数设置为true时会默认加载这些文件，我们也可以自定义
这些文件名称，只需将配置类型参数参数的设置改为我们自定义的名称即可

通用配置如下代码：

在index.html入口文件中

  window.$docsify = {  
        homepage: 'index.html', --设置首页文件加载路径。适合不想将 README.md 作为入口文件渲染，或者是文档存放在其他位置的情况使用  
        themeColor: '#3F51B5', --设置主题颜色,替换主题色。利用 CSS3 支持变量的特性，对于老的浏览器有 polyfill 处理。  
        name: 'diagon文档库', --设置文档标题，会显示在侧边栏顶部。  
        repo: 'http://172.16.33.15:8787/diagon-test/',  --配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件  
        maxLevel: 4,  --默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级  
        subMaxLevel: 3,  --自定义侧边栏后默认不会再生成目录，你也可以通过设置生成目录的最大层级开启这个功能。  
        ga: 'UA-106147152-1',  
        coverpage:true, --启用封面页。开启后是加载 _coverpage.md 文件，也可以自定义文件名。  
        executeScript: true,  --执行文档里的 script 标签里的脚本，只执行第一个 script (demo)。 如果 Vue 存在，则自动开启  
        loadNavbar:true,  --加载自定义导航栏，参考定制导航栏 了解用法。设置为 true 后会加载 _navbar.md 文件，也可以自定义加载的文件名。   
        mergeNavbar: true,   --小屏设备下合并导航栏到侧边栏。  
        auto2top: true,  --切换页面后是否自动跳转到页面顶部。  
        loadSidebar: true,  --加载自定义侧边栏，参考多页文档。设置为 true 后会加载 _sidebar.md 文件，也可以自定义加载的文件名。  
        autoHeader: true,   --同时设置 loadSidebar 和 autoHeader 后，可以根据 _sidebar.md 的内容自动为每个页面增加标题。  
        nameLink: {   --点击文档标题后跳转的链接地址。  
         '/zh-cn/': '/zh-cn/',  
         '/': '/'  
        },  
    search: 'auto', // 默认值    --全文搜索 - Search  

    search : [  
      '/',            // => /README.md  
      '/guide',       // => /guide.md   
      '/get-started', // => /get-started.md  
      '/zh-cn/',      // => /zh-cn/README.md  
    ],   

    // 完整配置参数  
    search: {  
      maxAge: 86400000, // 过期时间，单位毫秒，默认一天  
      paths: [], // or 'auto'  
      placeholder: 'Type to search',  

      // 支持本地化  
      placeholder: {  
        '/zh-cn/': '搜索',  
        '/': 'Type to search'  
      },  

      noData: 'No Results!',  

      // 支持本地化  
      noData: {  
        '/zh-cn/': '找不到结果',  
        '/': 'No Results'  
      },  

      // 搜索标题的最大程级, 1 - 6  
      depth: 2  
    }
  }

以上是index.html入口文件常用配置。其他详细内容请见文档内容
地址：https://docsify.now.sh/zh-cn/

文档的操作方法：

如果自己的文档有单独的类型可以创建单独的目录文件存放以方便做区分管理
将自己文档分好类型编写完成后将文档添加到左侧边栏中我们需要在_sidebar.md文件中添加自己的文档访问路径
格式如下：

- 文档类型分类   
- 文档类型分类  
 - [文档名称](/访问路径<文件名称即可>)  
- [用户使用介绍](/introduce)  
 访问路径可以多级如下：  
- [文档名称](/<目录名称>/<文件名称>)  
 - [用户使用介绍](zh-cn/introduce) 
 添加图片的格式：  
  ![](存放目录/图片名称) 

确认编写完成后，做更新（git pull），提交（git add . 和 git commit -m “什么文档”），确认有无异常（git status），确认处理完异常后推送远端 (git push)，然后去页面预览效果看是否正常

文档页面推送后自动更新

docsify支持即时修改即时页面生效功能，但是只对发布目录（在服务器端）有效。为了实现每个用户push文档就自动更新服务器端的效果。这里利用gitlab的webhook监听push事件，一旦有用户push了文档，那么服务器端的一个小程序就会对发布目录做git pull操作。这样就完成了任何人修改都能即时更新页面的效果。

​ 下面是步骤：

1. 从gitlab上拉取代码库，到服务器端

   cd /home/test/doc  
   git clone git@192.16.22.16:big-datas/docs.git  
   

   ​

2. 启动docsify，端口4321

   nohup docsify serve ./docs/ --port 4321 > docsify.log &  
   

   ​

3. 编写拉代码的脚本

   #!/bin/sh  
   cd /home/test/doc/docs  
   git pull  
   

   ​

4. 缓存git密码，首次pull拉取后的pull不再需要输入密码

   git config --global credential.helper store  
   

   ​

5. 启动gitlab webhook监听,其中dir指定脚本运行的目录，cmd指定要运行的脚本

   nohup java -jar doc-push-watcher-1.0-SNAPSHOT-exec.jar --dir=/home/test/doc --cmd=./pull.sh > watch.log &  
   

   ​

6. 配置docs.git项目的push监听

   1. 进入gitlab的该项目页面，点击Setting》Integrations，Url中输入：

   http://192.16.22.16:5432/event  
   

   2. 勾选，pull event，取消勾选Enable SSL verification
   3. 点击 “Add webhook” ​

7. 打开http://192.16.22.16:4321访问文档页面

8. 本地clone文档源，修改文件push到master上，观察文档页面变化