Gitlab Wiki最佳实践
介绍
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
等,很早就有用这种写代码写博客的功能了。
··· 完 ···
版权声明: 本博客所有文章除特别声明外,均采用CC BY-NC-SA 3.0许可协议,转载请注明出处。