使用markdown+gitlab管理团队知识库
作者：艾志谋
时间：2017/09/16
版本：1.0
我们公司目前的技术知识库是用word编写，然后统一用公司的gitlab管理。这样做的优点是可以统一管理所有人的知识文档，并实现对内开放，对外封闭。
但是缺点也很明显：
- word不适合做技术文档的编写。因为技术文档中有大量的代码片段，word中很难控制代码的格式，并且不能实现代码高亮，代码可读性大大下降。
- 微软office套件中的word目前只支持Windows平台和Mac OS平台，对于使用Linux平台的同事来说，虽然有可用的office替代品，但是效果差很多，可能会出现格式错乱的情况
- word是以二进制格式保存文件的，这样git无法对其实现版本追踪，在gitlab中也无法直接查看和编辑，必须要下载到本地才能查看和编辑，而且不支持增量更新，非常麻烦。
为此我强烈推荐使用markdown格式来编写技术文档，辅之以公司的gitlab平台来管理文档
1. 什么是markdown?
Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。
我们可以把它理解为一个标签库，类似于一种简化的HTML标签。比如我在一句话前面加上一个 # 号，它就会变成一个一级标题，加两个 ## 就会变成二级标题，等等。
关于markdown的简单介绍可以参考百度百科：markdown
更详细专业的介绍可以参考维基百科：markdown
2. 使用markdown相对word有什么优点？
- markdown使用语法极其简单，上手快，使用简单，排版效果出众。其实对于程序员编写技术文来说，并不需要word中的绝大部分高级功能，仅仅需要多级标题、序列、引用、超链接等基础排版功能就足够了，而这些基础功能在markdown中使用极其简单，你只需要记住几个标记，便可以在编写文档时双手不用离开键盘，文档和排版一气呵成，最关键的是markdown支持各种代码语法高亮！！！这个功能简直是程序员的福音！
在word中，一段代码的显示效果是这样的：
world中显示代码.png
在markdown中，一段代码的显示效果是这样的：
markdown中显示代码.png
高下立判。
-
markdown是一种纯文本格式的文档。这意味着任何文本编辑器都可以直接编写markdown格式的文本，任何系统自带的文本编辑器都可以，无需下载额外工具，你所需要做的仅仅是在普通文本的前面加上所需的标签，例如在一级标题的前面加上一个 # 号，在二级标题的前面加上 ##
-
GitHub和GitLab等主流代码托管网站都支持markdown格式文本在线查看和编辑（渲染后带格式的markdown格式文本阅读和原格式文本编辑）。这意味着查看和修改文档再也不用先下载到本地，打开word编辑，再上传了。git项目的README.MD文件就是一个自动生成的markdown格式文本，markdown格式文本的后缀名为.md
-
使用markdown配合公司内部的GitLab可以在保持现有所有优点的情况下增加在线阅读、在线编辑、本地纯文本编辑、追踪编辑历史、快速排版、代码高亮等优点。
-
markdown文本可以轻松导出为PDF、HTML文件，无论在线传播还是阅读，都极其方便。
3. markdown如何使用？
对普通人来，带符号的文本可能会让人感到害怕，但是对程序员来说，markdown简直再简单不过了。markdown设计时虽然借用了HTML的某些思想，但是其设计初衷并不是专为程序员设计，而是为所有希望摆脱繁杂排版工作的写作爱好者所设计，现在已经有越来越多的写作爱好者开始使用并积极推广markdown。
关于markdown的简单使用可以参考简书的这篇文章：献给写作者的 Markdown 新手指南
对于基本常用的语法，文章中都说的很清楚明白，这里我要补充一点的是：
在文章中写代码块的时候，可以在三个`的后面加上语言类型，例如：``` java 表示代码块中为java代码，不同的语言代码有不同的语法高亮。
高级用法可以参考markdown官方中文指南Markdown 语法说明 (简体中文版)
虽然markdown文件是一种纯文本，用各个操作系统自带的文本编辑器都可以打开并编辑，但是直接看源文件还并不够直观，我们最好能用一个一边编写一边预览效果的编辑器。关于markdown编辑器的推荐，可以参考月光博客的这篇文章：好用的Markdown编辑器一览，Web、Windows、Mac OS、Linux、Android、ios各个平台的都有介绍到
4. 如何在公司的GitLab上使用markdown来替代word，做技术文档的编写和管理？
我们公司中台知识库的GitLab地址如下：汉得中台知识库
- 我们将这个项目克隆到本地：
git clone https://rdc.hand-china.com/gitlab/ztjszx/knowledge.git - 然后新建自己的本地分支，以我自己的分支为例：
git branch asimov，并切换到自己本地的分支git checkout asimov - 然后在自己所属的部门目录下新建自己的文件夹，在文件夹中添加自己的文档，如：
使用markdown+gitlab管理团队知识库.md - 执行
git add和git commit，并推送到自己的远程分支:git push origin asimov - 切换到master分支
git checkout master，合并自己的分支git merge asimov，推送到远程master分支git push origin master
5. 在GitLab上在线操作文档
- 提交完我们的文档后，我们去GitLab上看看我们的文档是什么效果，如下：
提交文档.png
- 点击文档即可在线查看，效果如下：
在线查看的效果.png
红框中的三个按钮分别是：打开源文件、预览文件、复制源文件、在新窗口中查看源文件、编辑。
- 查看源文件可以看到这篇文档的md原始文件，效果如下：
查看原始文件的效果.png
- 编辑按钮可以让你直接在先编辑md源文件，并实时预览编辑效果：
在线编辑.png
红框中的Write和Preview可以随时在编辑和预览模式中切换。
- 下图红色框框中的两个按钮Blame和History可以实现该文档的编辑历史追溯：
文件编辑历史.png
Blame可以查看何人在何时修改了该文档的那些内容，效果如下：
blame.png
History可以查看文档的修改和提交历史概览，效果如下：
history.png
ps：在本地也可以使用git log -p 文件名命名来查看某个指定文件的修改历史，但是Windows的cmd和power shell对中文的支持都不好，中文内容会显示为乱码，如下：
本地git log.png
由于我没有mac和Linux平台，所以也无从得知这两个平台是否会显示乱码，希望大家自行测试。
自此，我们已经可以使用markdown+gitlab的方式来管理公司内部所有的技术文档，实现文档分布式管理、协同编辑、历史追溯、权限管理、在线查看、在线编辑等功能。
希望大家在写技术文档时早日告别word，迎接markdown。
网友评论