使用markdown+gitlab管理团队知识库

作者：艾志谋
时间：2017/09/16
版本：1.0

我们公司目前的技术知识库是用word编写，然后统一用公司的gitlab管理。这样做的优点是可以统一管理所有人的知识文档，并实现对内开放，对外封闭。
但是缺点也很明显：

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

为此我强烈推荐使用markdown格式来编写技术文档，辅之以公司的gitlab平台来管理文档

---

1. 什么是markdown?

Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。

我们可以把它理解为一个标签库，类似于一种简化的HTML标签。比如我在一句话前面加上一个 # 号，它就会变成一个一级标题，加两个 ## 就会变成二级标题，等等。
关于markdown的简单介绍可以参考百度百科：markdown
更详细专业的介绍可以参考维基百科：markdown

2. 使用markdown相对word有什么优点？

1. markdown使用语法极其简单，上手快，使用简单，排版效果出众。其实对于程序员编写技术文来说，并不需要word中的绝大部分高级功能，仅仅需要多级标题、序列、引用、超链接等基础排版功能就足够了，而这些基础功能在markdown中使用极其简单，你只需要记住几个标记，便可以在编写文档时双手不用离开键盘，文档和排版一气呵成，最关键的是markdown支持各种代码语法高亮！！！这个功能简直是程序员的福音！

在word中，一段代码的显示效果是这样的：

world中显示代码.png

在markdown中，一段代码的显示效果是这样的：

markdown中显示代码.png

高下立判。

2. markdown是一种纯文本格式的文档。这意味着任何文本编辑器都可以直接编写markdown格式的文本，任何系统自带的文本编辑器都可以，无需下载额外工具，你所需要做的仅仅是在普通文本的前面加上所需的标签，例如在一级标题的前面加上一个 # 号，在二级标题的前面加上 ##

3. GitHub和GitLab等主流代码托管网站都支持markdown格式文本在线查看和编辑（渲染后带格式的markdown格式文本阅读和原格式文本编辑）。这意味着查看和修改文档再也不用先下载到本地，打开word编辑，再上传了。git项目的README.MD文件就是一个自动生成的markdown格式文本，markdown格式文本的后缀名为.md

4. 使用markdown配合公司内部的GitLab可以在保持现有所有优点的情况下增加在线阅读、在线编辑、本地纯文本编辑、追踪编辑历史、快速排版、代码高亮等优点。

5. 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地址如下：汉得中台知识库

1. 我们将这个项目克隆到本地：git clone https://rdc.hand-china.com/gitlab/ztjszx/knowledge.git
2. 然后新建自己的本地分支，以我自己的分支为例：git branch asimov，并切换到自己本地的分支git checkout asimov
3. 然后在自己所属的部门目录下新建自己的文件夹，在文件夹中添加自己的文档，如：使用markdown+gitlab管理团队知识库.md
4. 执行git add和git commit，并推送到自己的远程分支:git push origin asimov
5. 切换到master分支git checkout master，合并自己的分支git merge asimov，推送到远程master分支git push origin master

5. 在GitLab上在线操作文档

1. 提交完我们的文档后，我们去GitLab上看看我们的文档是什么效果，如下：

提交文档.png

2. 点击文档即可在线查看，效果如下：

在线查看的效果.png

红框中的三个按钮分别是：打开源文件、预览文件、复制源文件、在新窗口中查看源文件、编辑。

3. 查看源文件可以看到这篇文档的md原始文件，效果如下：

查看原始文件的效果.png

4. 编辑按钮可以让你直接在先编辑md源文件，并实时预览编辑效果：

在线编辑.png

红框中的Write和Preview可以随时在编辑和预览模式中切换。

5. 下图红色框框中的两个按钮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。