介绍

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.mdwiki页面的全局侧边栏。如果没有这个文件,Gitlab会有一套默认的侧边栏规则。

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

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

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

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

总结的几个约定

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

为什么是最佳实践

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

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

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