文档服务

使用Docker+Docsify搭建文档服务

Docker环境配置

• 安装Docker，Link:Centos7上安装配置Docker

• 安装Docker Compose，Link:Docker Compose安装与简单使用

• 编写DockerFile.onbuild文件，并使用该文件构建出基础镜像供后续使用

  FROM node:lts-stretch-slim
  
  RUN npm i docsify-cli -g --registry=https://registry.npm.taobao.org
  
  ONBUILD COPY docs /srv/docsify/docs
  ONBUILD WORKDIR /srv/docsify
  
  CMD ["/usr/local/bin/docsify", "serve", "docs"]

  $ docker build -t docsify:onbuild -f Dockerfile.onbuild .

Docsify项目准备

项目结构说明:

项目跟路径
 ┣ docs
 ┃ ┃  ┣_sidebar.md  # 文档左侧导航
 ┃ ┣ _coverpage.md  # 文档首页导航
 ┃ ┗ index.html     # 文档右上角导航
 ┣ docker-compose.yml
 ┣ Dockerfile
 ┗ Dockerfile.onbuild

• docker-compose.yml

  用于在Gitlab-Runner上启动文档容器的脚本，内容如下

  version: '3.7'
  
  services:
    nodejs-docsify:
      image: my-docsify
      build:
        context: .
      container_name: nodejs-docsify
      hostname: docsify
      ports:
        - 80:3000
      volumes:
        - ./docs:/srv/docsify/docs
      #restart: always
      environment:
        - TZ=Asia/Shanghai

• DockerFile

  用于构建进行的脚本，内容固定如下

  FROM docsify:onbuild

  其中docsify:onbuild是在第一步Docker环境准备时打的基础镜像，参考Dockerfile.onbuild

Docsify文档说明

项目文档采用Markdown编写，由Docsify实时渲染

• 文档主体

  文档主体在doc目录下，每个项目单独一个目录。例如:

  消息队列的项目文档放在src/document下，图片文件放在src/document/images目录下

• 文档目录(侧边栏)

  文档目录在docs/项目目录/_sidebar.md文件中，每个项目有单独的文档目录

  例如:消息队列的文档目录在docs/document/_sidebar.md中，内容如下

  - 产品介绍
    - [背景](document/01.introduction/background.md)
  
  - 产品设计文档
    - [应用信息设计](document/02.design-document/application_information_design.md)
  
  - 用户使用手册
    - [用户指南](document/03.user-guide/user-guide.md)
  
  - 运维手册
    - [监控报警事项](document/04.devops-guide/monitor_alarm.md)
  
  - OKR
    - [OKR 目标](document/05.okr-summary/okr.md)

开发方式

改动提交到 master 分支后，会触发CI，稍等片刻再访问文档地址就可以看到相应的变化

• Docsify对Markdown语法进行了扩展，如果你想让文档的表现力更好，可以参考 Docsify Markdown扩展

• 标题锚点ID的生成规则:例如# ## ### 等标题会生成标题锚点用于跳转，ID生成规规则为:

  • 如果标题由数字开头生成的ID前面会添加 _下划线
  • 标题中包含空格的会被转成-中横杠【例如 # 1. 背景生成的ID为 _1.-背景】
  • 如果不想使用默认的ID生成规则，可以为标题添加id属性【### 你好，世界 :id=hello-world】

• 页面间跳转方式:以上面文档目录为例，在本页面想要跳转到背景的二级标题 概述 那么应该写成

  [跳转概述](#概述)

  不同文件间的跳转必须加上完整的项目路径，跳转到具体的标题锚点应该使用渲染后的锚点ID，如

  [跳转应用信息设计](document/02.design-document/application_information_design.md)

文档服务效果图

附录

• 参考文档:

  • .gitlab-ci.yml语法详解 https://docs.gitlab.com/ee/ci/yaml/
  • docsify文档生成器 https://docsify.js.org/#/?id=docsify-494
  • VuePress静态网站生成器 https://vuepress.vuejs.org/zh/guide/

• UML支持

  Markdown扩展支持PlantUML

  例如代码块:

  ​```plantuml
  Alice -> Bob: 你好！！
  ​```

  将会生成时序图:

  

  而如下代码块

  ​```plantuml
  class Car
    
  Driver - Car : drives >
  Car *- Wheel : have 4 >
  Car -- Person : < owns
  ​```

  将会生成类图: