前言
这个帮助文档的功能，是模仿阿里云的帮助文档实现的。如下图，是阿里云ECS产品的帮助文档。
其中左侧导航区域，是对应数据库里的一张文档表，一条数据关联一个md文件，而且要注意到，数据是有上下级关系的，也就是一个树。右侧区域，其实就是一个markdown文件的内容。前端（不管是vue还是react）都是可以借助控件解析md文件，达到这样的预览效果。
为什么是用md文件而不是word或其它的文件？
使用word文件的缺点
- word不适合做技术文档的编写。因为技术文档中有大量的代码片段，word中很难控制代码的格式，并且不能实现代码高亮，代码可读性大大下降。
- 微软office套件中的word目前只支持Windows平台和Mac OS平台，对于使用Linux平台的同事来说，虽然有可用的office替代品，但是效果差很多，可能会出现格式错乱的情况
- word是以二进制格式保存文件的，这样git无法对其实现版本追踪，在gitlab中也无法直接查看和编辑，必须要下载到本地才能查看和编辑，而且不支持增量更新，非常麻烦。
那什么是markdown?
Markdown 是一种轻量级标记语言，它以纯文本形式（易读、易写、易更改）编写文档，并最终以 HTML 格式发布。Markdown 也可以理解为将以 MARKDOWN 语法编写的语言转换成 HTML 内容的工具。该语言有很多方言，一般文件后缀为 .md 或者 .markdown。GitHub 可以直接预览 Markdown，所以一些人会在 gitHub 上写博客和简历。
Markdown 语法入门总结
| markdown 命令 | html 格式的预览效果说明 | |
| 1 | #（#后有一个空格） | 一级标题（有几个#号就代表有几级标题，一共用六级，字体大小逐级递减） |
| 2 | 单行文字下一行添加多个 = 或 – | 如果在文字行的正下方一行输入多个 = / -，该文字会显示成一 / 二级标题 |
| 3 | 回车（一个回车或两个回车） | 有的场景是一个回车换行，有的场景是两个回车换行 |
| 4 | （一个或多个空格） | 使用 可以实现段落文本的首行缩进的效果 |
| 5 | [链接文字](链接地址) | 超链接，比如：[百度](www.baidu.com)，预览的时候可点击 |
| 6 | ！[图片描述]（图片地址） | 图片，图片地址正确无误的情况下，预览的时候会显示一张图片 |
| 7 | > 符号，或者两个 > 符号 | 区块引用，在段落的每行或者只在第一行使用符号 >，还可使用多个嵌套引用 |
| 8 | *斜体*、_斜体_、**粗体**、__粗体__ | 在强调内容两侧分别加上 * 或者 _，加单个的 */_ 表示斜体，两个 */_ 表示粗体 |
| 9 | ***斜体+粗体***、___斜体+粗体___ | 在强调内容两侧分别加上 * 或者 _，加三个的 */_ 表示斜体 + 粗体叠加的样式 |
| 10 | ~~文本上显示删除线~~ | |
| 11 | 代码、制表符+代码 |
一行代码，代码，四个空格和单个制表符也可以表示代码 |
| 12 | 多行代码 |
多行代码，两个 或 ~~~ 包起来，可在第一行 |
| 13 | * ，1. （* 和数字后面又一个空格） | * 号加空格表示无序列表，数字加空格表示有序列表 |
| 14 | ||
| Markdown 只关注内容不关注样式，开始学语法可以预览一下学会了语法就不要再预览，这样可以提高效率。 | ||
如何在gitlab上维护md文件？
首先可以在本地用任何编辑器（常用的是typora），编辑完上传到gitlab上。也可以直接在gitlab上编辑预览。
md文件在gitlab上的预览效果
帮助文档功能的具体实现步骤
- 在gitlab上维护md文件，例如“什么是云服务器ECS.md”、“产品优势.md”、“应用文档.md”等。
- 把维护好的文件上传到文件服务器（S3、fastdfs、minio等等都行）。
- 准备每个文档的数据（如标题、作者、创建时间、url），关联好对应文档在文件服务器上的url，插入数据库。
- 后台接口查出当前产品（这边是ECS）的所有文档（注意返回的是树结构）
- 前端拿到数据后，用户点击哪个文档，就展示对应md文件的预览效果即可，我虽然不经常写前端代码，但是我知道若要在vue里实现在线编辑md文件也不难。
+1
