使用 Typora+docsify+GitHub Pages 搭建团队知识库

在实际工作中,搭建团队知识库是非常有必要的,比如:

  • 随着项目的迭代,有很多信息需要共享。需求、系统环境信息、任务分配情况、各端开发规范等。这些信息不能只留在某几个人的脑子里,如果有人离职,那这些就成了实实在在的坑。
  • 有些项目属于提供方,比如中间件,需要提供中间件使用指引;中台系统,需要提供接口文档给前端。

不少团队将文档整理成 Word、Excel 格式,需要的时候再发给人家。这样其实很不方便,一是传达不方便,总有遗漏的人没收到;二是更新不方便,你更新了文档别人可能还拿的旧文档开发。

所以在团队中,搭建一个 在线的 知识库是非常有必要的。

使用 docsify

docsify 是一个可简单快速生成一个小型的文档网站的工具。

其实市面上类似的工具很多,如:阿里的语雀、DokuWiki、MDwiki、HDwiki 等。为什么选择 docsify?

我认为其有如下优点:

  • 大部分文档不需要很复杂的样式,docsify 使用 Markdown 格式,编辑方便。
  • 部署简单,不需要搭建后台服务、数据库等。docsify 核心就是一个 HTML,再实时渲染编辑的 Markdown 文件。
  • 可自定义菜单,并根据解析的 Markdown 文件结构自动生成目录。
  • 支持全文检索,这很有用。

所以有兴趣的可以跟随官网的指引搭建一个了解下,绝对不错~

官网地址:https://docsify.js.org/#/zh-cn/

使用 Typora

Typora 又是个什么东东?

上面写到使用 Markdown 写文档,那就需要一个比较好用的 Markdown 编辑器啊!没错,Typora 就是个 Markdown 编辑器。

我们知道,Markdown 其实是纯文本,通过特定字符来描述样式。很多编辑器呈现两栏,左边是源文件,右边是呈现的样式。Typora 则更方便,直接在编辑区所见所得。而且还有各式各样的主题可选择。

反正就是一个很好用的 Markdown 编辑器啦!

官网地址:https://www.typora.io/

使用 GitHub Pages

很愉快的使用 Typora 编辑好文档后,当然是要部署了。

由于 docsify 就是个静态站点,随便找个服务器丢上去就可以了,比如:Apache、nginx。

但是也有个问题:文档肯定是多人写的,我们一般会保存在 SVN/Git 上,那每次改完后我们都要更新最新文档,打包上传到服务器,这稍显麻烦!

使用 GitHub Pages 就可以减少中间上传那一步。它像一个静态空间,空间呈现的内容就是你提交到 Github 上的代码,由于 docsify 的文件都是静态的,不需要编译,所以提交代码后网站内容就直接呈现出来了。

官网地址:https://pages.github.com/

国内也有类似的服务:码云 Pages

总结

随着行业的发展,各种好用的工具层出不穷。我们作为行业人员,更应该善于利用这些工具提升自身工作的效率和质量。

最后,感谢这些作者的贡献。