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

3,336 阅读5分钟

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

SpringBoot实战电商项目mall(50k+star)地址:github.com/macrozheng/…

语雀简介

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

主要使用场景如下:

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

效果展示

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

核心概念

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

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

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

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

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

  • 知识:知识库中的内容,可以是文档。

搭建

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

快速搭建

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

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

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

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

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

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

自定义首页

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

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

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

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

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

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

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

公开访问

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

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

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

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

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

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

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

总结

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

官方网站

www.yuque.com/

本文 GitHub github.com/macrozheng/… 已经收录,欢迎大家Star!