介绍

Gitlab中每个代码库有一个wiki功能，可以方便的为项目编写相关的wiki。一般也可以建一个空项目作为团队的知识库。

但是Gitlab的wiki功能不够完善，尽管提供了一个可视化编辑界面来编写文档。但是文档之间的链接，上传的附件等，都不太好维护。如果没有好的组织管理，很容易导致wiki最后杂乱无章。

Gitlab也提供代码库的方式来管理wiki。所以，这里介绍下我基于此在Gitlab中写wiki的最佳实践。

最佳实践

clone repo

首先，新建一个wiki仓库后，clone到本地

git clone ${WIKI代码库}.wiki.git

之后，本地会看到一个空的目录。接下来就可以进行编写了。

目录结构和规则

一个标准的wiki目录结构如下

图片

Gitlab左边菜单点击wiki菜单项指向的就是home.md。

_sidebar.md是wiki页面的全局侧边栏。如果没有这个文件，Gitlab会有一套默认的侧边栏规则。

uploads是wiki的附件资源上传的路径。这个目录也是Gitlab中默认的附件上传路径，我们遵循这个规则，把附件都放这个目录。里面可以新建子目录。

需要注意的是，wiki中的链接。所有的链接默认根目录都是wiki根目录，所以需要填写完整地址。根目录只需要文件名即可。此外，链接不要带.md后缀，只需要文件名即可。否则会打开成一个md文件。

另外，wiki系统会将文件名输出成文档的大标题。所以，建有意义的名字。

如上即是Gitlab的wiki系统默认的几个规则。开发者可以基于这些规则来建立其他的目录，分类不同的文档。

总结的几个约定

  • 不要在Gitlab界面中直接编写wiki
  • 文件名即是标题
  • 不要随意建目录，除非目录有意义
  • 良好的markdown格式。写markdown就像写代码，良好的格式会赏心悦目

为什么是最佳实践

首先，wiki类似于代码，也是一种产物。既然类似于代码，就应该要落地，最好是用版本管理的方式进行维护。这样，日后即使迁移备份等，都比较方便。

为什么不用Gitlab自带的编辑器编辑。首先，自带的编辑器也不是很优秀。何况，本地有一堆的优秀markdown编辑器，体验更好。此外，自带的编辑器没有目录选择，靠约定在标题中输入路径。如果某个同事写错路径了，外界无感知，但是实际上是把底层的代码库弄乱了。

用代码管理的方式写wiki并不新鲜。像Github Pages等，很早就有用这种写代码写博客的功能了。