使用gitlab+markdown实现物联网门户的帮助文档功能

前言

这个帮助文档的功能，是模仿阿里云的帮助文档实现的。如下图，是阿里云ECS产品的帮助文档。

其中左侧导航区域，是对应数据库里的一张文档表，一条数据关联一个md文件，而且要注意到，数据是有上下级关系的，也就是一个树。右侧区域，其实就是一个markdown文件的内容。前端（不管是vue还是react）都是可以借助控件解析md文件，达到这样的预览效果。

为什么是用md文件而不是word或其它的文件？

使用word文件的缺点

1. word不适合做技术文档的编写。因为技术文档中有大量的代码片段，word中很难控制代码的格式，并且不能实现代码高亮，代码可读性大大下降。
2. 微软office套件中的word目前只支持Windows平台和Mac OS平台，对于使用Linux平台的同事来说，虽然有可用的office替代品，但是效果差很多，可能会出现格式错乱的情况
3. word是以二进制格式保存文件的，这样git无法对其实现版本追踪，在gitlab中也无法直接查看和编辑，必须要下载到本地才能查看和编辑，而且不支持增量更新，非常麻烦。

那什么是markdown?

Markdown 是一种轻量级标记语言，它以纯文本形式（易读、易写、易更改）编写文档，并最终以 HTML 格式发布。Markdown 也可以理解为将以 MARKDOWN 语法编写的语言转换成 HTML 内容的工具。该语言有很多方言，一般文件后缀为 .md 或者 .markdown。GitHub 可以直接预览 Markdown，所以一些人会在 gitHub 上写博客和简历。

Markdown 语法入门总结

如何在gitlab上维护md文件？

首先可以在本地用任何编辑器（常用的是typora），编辑完上传到gitlab上。也可以直接在gitlab上编辑预览。

md文件在gitlab上的预览效果

帮助文档功能的具体实现步骤

1. 在gitlab上维护md文件，例如“什么是云服务器ECS.md”、“产品优势.md”、“应用文档.md”等。
2. 把维护好的文件上传到文件服务器（S3、fastdfs、minio等等都行）。
3. 准备每个文档的数据（如标题、作者、创建时间、url），关联好对应文档在文件服务器上的url，插入数据库。
4. 后台接口查出当前产品（这边是ECS）的所有文档（注意返回的是树结构）
5. 前端拿到数据后，用户点击哪个文档，就展示对应md文件的预览效果即可，我虽然不经常写前端代码，但是我知道若要在vue里实现在线编辑md文件也不难。