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

ecs文档

前言

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

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 语法入门总结

markdown 命令 html 格式的预览效果说明
1 #(#后有一个空格) 一级标题(有几个#号就代表有几级标题,一共用六级,字体大小逐级递减)
2 单行文字下一行添加多个 = 或 – 如果在文字行的正下方一行输入多个 = / -,该文字会显示成一 / 二级标题
3 回车(一个回车或两个回车) 有的场景是一个回车换行,有的场景是两个回车换行
4   (一个或多个空格) 使用   可以实现段落文本的首行缩进的效果
5 [链接文字](链接地址) 超链接,比如:[百度](www.baidu.com),预览的时候可点击
6 ![图片描述](图片地址) 图片,图片地址正确无误的情况下,预览的时候会显示一张图片
7 > 符号,或者两个 > 符号 区块引用,在段落的每行或者只在第一行使用符号 >,还可使用多个嵌套引用
8 *斜体*、_斜体_、**粗体**、__粗体__ 在强调内容两侧分别加上 * 或者 _,加单个的 */_ 表示斜体,两个 */_ 表示粗体
9 ***斜体+粗体***、___斜体+粗体___ 在强调内容两侧分别加上 * 或者 _,加三个的 */_ 表示斜体 + 粗体叠加的样式
10 ~~文本上显示删除线~~ 文本上显示删除线,这就是上面 ~ markdown 语法所渲染出的文本样式
11 代码、制表符+代码 一行代码,代码,四个空格和单个制表符也可以表示代码
12 多行代码、~~~多行代码~~~ 多行代码,两个 或 ~~~ 包起来,可在第一行 或 ~~~ 后指定编码语言
13 * ,1. (* 和数字后面又一个空格) * 号加空格表示无序列表,数字加空格表示有序列表
14
Markdown 只关注内容不关注样式,开始学语法可以预览一下学会了语法就不要再预览,这样可以提高效率。

如何在gitlab上维护md文件?

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

md文件在gitlab上的预览效果

md文件在gitlab上的预览效果
md文件在gitlab上的预览效果

源码界面

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

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

《使用gitlab+markdown实现物联网门户的帮助文档功能》有2个想法

发表评论

邮箱地址不会被公开。