前言
部门目前搭建了自己的gitlab服务器, 用于代码管理, 但是其实gitlab的功能不止于此, 这不, 近期研究了下关于部门技术文档管理的方法, 就发现了gitlab的wiki功能, 为我们的文档管理提供了完美的解决方案, 下面就对此进行一些说明, 并记录一下自己的踩坑与填坑经历.
关于wiki
网上有一个公式, git + markdown = wiki, 虽然不是很准确(因为wiki不只是支持markdown), 但却是很直观的解释了什么是wiki, wiki就是利用git来进行文档管理的一种方法, 就好像我们用git管理代码一样.
gitlab上wiki的使用
wiki的使用很简单, 只要我们登陆到gitlab, 进入到wiki界面一看便知, 直接可以创建页面, 侧边栏可以查看已经创建的文档, 进入文档后可以浏览, 也可以进行编辑, 编辑完可以直接提交, 当然也可以写提交日志, 非常简单, 这里就不贴图了.
上面说的是在线操作, 但其实它和代码管理一样, 也可以克隆到本地进行修改, 然后再提交推送. 我们需要先进入wiki页面(在右侧边栏有一个'更多页面'按钮), 进入后就可以找到克隆地址了, 使用你熟悉的方法克隆到本地, 然后就可以在本地进行编辑了.
gitlab的markdown语法
我也不确定gitlab的markdown语法是否标准, 就目前使用的情况来看可能会与一些其他的markdown编辑器在语法上有些不同, 比如不支持toc(当然这是扩展命令), 还有我这篇文章中提到的锚点等, 但我觉得大部分语法都是通用的, 大家在使用过程中如果发现不兼容的地方可以记录下, 尤其是习惯在本地操作的, 可能需要和一些编辑器进行兼容, 这样也方便我们导出为其他格式的文档.
关于本地操作使用的工具
官方建议的是使用gollum, 但其实我一直也没试用过这个工具, 看网上说虽然它的安装步骤很简单, 但它需要一些环境依赖, 真正安装起来其实挺麻烦的, 而且我看介绍它也是在浏览器中进行编辑, 我不习惯, 所以直接没有尝试.
这里我想给大家推荐一款工具 -- Typora.
这款软件在markdown编辑软件中应该还是挺出名的(关于markdown的编辑软件, 我这篇文章有说明, 感兴趣的可以移步),.
- Typora是一款实时渲染的工具, 你在使用markdown写作时, 它可以实时转换markdown格式, 方便你查看排版;
- Typora支持toc命令, 可以一键生成目录, 而且亲测它生成的目录在gitlab的wiki中是兼容的;
- Typora的图片没有居中格式, wiki中的图片可以通过图片居中来实现图片居中显示, 而这种方式在Typora中不支持, 而且连图片也不显示, 为了兼容, 建议在wiki中使用图片居中进行图片居中时, 在后多加一个空行, 这样的话在wiki仍然可以居中, 而且可以保证在typora中图片也能显示, 如果是文字居中的话, 是可以使用
来实现的; - Typora可以在侧边栏显示目录结构图, 方便本地文档的管理;
- Typora支持的导出格式非常多, 感觉完全可以替代gitbook了都.
- 如果将Typora的图片插入设置为相对路径优先, 并且自动复制到指定目录下的话, 可以实现和gitlab的无缝连接, 在本地编辑好, 连带图片一起推送, 在gitlab可以完美显示图片.
最后
由于我也是刚开始使用wiki和Typora, 所以有很多地方还不熟悉, 如果有说错的地方还请大家留言指正,.
如果自己的文章对你多少有点帮助的话, 还请您动动手指给点个赞哦.