无需开发部署，秒建优雅的开源项目文档，这个工具用起来贼爽

之前介绍过几款搭建开源项目文档的工具，有Docsify、VuePress和Hexo。这些工具有个共同点，需要一些开发部署的工作，部署基本依赖Github Pages或者自建服务器。那么有没有那种开箱即用的工具呢，最近发现很多开源项目都用语雀来搭建文档网站，体验了一把，非常不错，推荐给大家！

SpringBoot实战电商项目mall（50k+star）地址：https://github.com/macrozheng/mall

语雀简介

语雀是新一代的云端知识库，可以写出像书一样的项目文档，拥有专业好用的编辑器（支持Markdown转换），方便的团队协同功能。

主要使用场景如下：

• 个人笔记：语雀知识库具有公开私有功能，私有的知识库完全可以当在线云笔记使用，可以方便我们记录点滴，沉淀知识。
• 专栏博客：如果你不想自己搭建博客网站的话，可以直接生成。
• 项目文档：可以多人协作的项目文档，你见过没？
• 官方文档：可以作为产品说明和帮助手册。

效果展示

我们先来看下成品效果，开箱即用，界面还是挺不错的！

核心概念

在使用语雀之前，我们需要对其中的概念有所了解。下面介绍下这些核心概念，然后再展示下对应的界面。

• 首先我们来看下各个核心概念的关系图，这对理解这些概念很有帮助：

• 空间：空间类似于公司或组织的概念，在空间中我们可以管理团队、知识库、知识等内容。

• 团队：空间下的团队可以和你实际组织结构进行挂钩，如部门团队，项目组等。

• 知识库：知识库是知识内容的载体，就好比一本书一样，你可以在知识库里对知识内容进行重新组织和分类。

• 知识：知识库中的内容，可以是文档。

搭建

接下来我们使用语雀来搭建一个开源项目文档，以我的开源电商项目mall为例。

快速搭建

• 首先我们点击左上角创建空间，用于存放团队和知识库；

• 然后选择创建知识库，由于我们的知识库主要用于存放文档，所以选择文档知识库，然后输入名称、简介即可；

• 创建完知识库之后，我们就可以在知识库中添加文档了，直接复制之前使用Markdown写的文档即可，然后点击右上角的立即转换；

• 转换成功后显示效果如下，是不是比自己搭建项目文档网站简单多了？

• 这里值得一提的是，在我们复制文章时，语雀会自动帮我们上传在线图片，很多博客网站也都有这个功能；

• 如果你想修改知识库的文档目录的话，比如我想整个二级目录，可以使用编排目录功能；

自定义首页

其实到这里，我们已经学会了如何制作一个开源项目文档网站了，但是此时文档网站的首页只是一个目录，这样未免有些单调，如果我们想要首页内容更丰富些，我就需要创建团队，然后自定义团队的首页即可；

• 首先我们来创建个团队，选择官方文档模板；

• 然后填写名称、简介、头像即可；

• 然后我们可以通过自定义首页功能，使用图形化界面来完成一个首页，下面是我已经完成好的首页效果；

• 这里我添加了搜索、知识库、自定义内容三个模块，如果你想首页更丰富些，可以添加更多模块试试；

• 这里最好在你的知识库的设置页，把你的知识库转移到创建的团队中去；

• 接下来访问你的团队主页，一个标准的开源项目文档网站就诞生了。

公开访问

如果你想搭建一个私有的文档网站的话，上面的操作基本能满足需求了，但如果你想搭建一个公开的文档网站的话，还需要如下操作。

• 很遗憾的是，在新建空间中的无论团队还是知识库，都是没法设置让互联网上的所有人访问的，仅支持如下三种访问权限；

• 要想团队可以公开访问，我们需要在默认的个人空间中，创建知识小组，可以选择官方文档模板；

• 此时我们可以发现，团队的可见范围变成了互联网可见，这才是真正公开的团队；

• 之后要做的就是把之前的知识库通过导入、导出功能转移到该团队中去，导出功能在知识库设置->高级设置中，选择导出为.lakebook格式；

• 然后在该知识小组中创建知识库，设置范围为互联网可见，并导入.lakebook文件；

• 之后再按照之前的步骤自定义知识小组的首页，一个可以公开访问的开源项目文档网站就诞生了！

总结

通过使用语雀搭建开源项目文档的一波实践，我们可以发现这种方式确实比使用Docsify来自建网站简单太多了，既不需要编码，也不需要买服务器。怪不得很多开源项目都用它来搭建文档网站，当然语雀的功能还不只这些，用来做在线云笔记也挺好用的，如果大家感兴趣的话，可以自己探索下！

官方网站

https://www.yuque.com/

本文 GitHub https://github.com/macrozheng/mall-learning 已经收录，欢迎大家Star！