文档服务

使用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)
```

文档服务效果图

附录

参考文档:

UML支持

Markdown扩展支持PlantUML

例如代码块:

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

将会生成时序图:

而如下代码块

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

将会生成类图:

anealo / nodejs-docsify