Docusaurus多库龙-创建一个漂亮的文档

今天我们介绍一个文档创建的工具-Docusaurus,官方没有做中文命名,我们暂且叫它“多库龙”,直译可以叫做文档龙之类的吧。这篇文字一个是介绍软件,还有一个是做讨论,官方确实有中文文档,但有很多内容我还是不明白,希望大家能够讨论明确制作过程。

这个可爱的小恐龙就是这个工具的图标。

那为什么要用这个东西来写文档?

我最近在一个没有工资的独立游戏项目组里面利用空闲时间写代码,写好的代码要给关卡设计的伙伴用,需要教会他们如何使用写好的功能,一开始我使用word制作的文档,发现找起来很麻烦,而且叙述的内容也很多,当涉及到需要查找关联的word时,需要设置很多超链接跳转打开另一个word。

其实我们需要的是一个手册一样的东西,以一定的结构性构成,例如Unity的官方文档。

观察Unity文档的结构,其实是一个网站,里面有很多的html,css,js等网页相关的文件,但现实条件是,我哪有那么多时间去给你写html,css,js这些,经过很长时间的搜索,终于找到一个合适工具,可以帮我们构建整个网站,我们只需要专注于网站内容的搭建-多库龙。

多库龙是免费的,他的功能就是用来创建静态网站的,而我们只需要写MarkDown文档即可,如果希望扩展也可以扩展网站功能。编写完后,你可以选择部署到服务器上(部署这一块我没看懂要怎么弄,求讲解),或者就放在自己本地运行看也可以。

下方是官方网址。

https://docusaurus.io/zh-CN/

如何创建,你可以跟着官方文档里面走,或者按我说的来。官方宣称5分钟搞定网站,这个取决于你的电脑和网速了,实际操作时间1分钟不到。

第一步,安装node.js。

官方要求Node.js 版本 >= 14 ,直接安最新的就好了。

https://nodejs.org/en/download/

一般大家用的是64位win10,选择正确的就行,然后安装好。

第二步,找个空的文件夹。

这个空的文件夹,将会作为你整个项目的根目录,注意使用英文文件夹名称。

第三步,打开控制台。

在空文件中,按住shift,点击右键,选择在此处打开Powershell窗口。

第四步,初始化项目。

在命令窗口,输入下面的内容,回车。

npx create-docusaurus@latest website classic

这句话的意思是,帮我创建一个最新版的多库龙项目,项目名叫website,项目模板是classic。有时系统会询问你是否要创建项目,按 y 回车创建。

系统就会开始自动创建项目。

这个过程比较长,多库龙会去搜索最新的模板,可能很长时间没有反应,不用动这个窗口,如果不想继续安装可以按ctrl+C。

安装好之后是下面这样的,如果你是第一次安装显示的内容可以有些不一样。

输入

cd .\website\

移动到项目中。

输入npm run start,运行网站。

多库龙分为两部分编译,一部分是服务器,一部分是客户端。

编译成功后应该会自动打开网址

http://localhost:3000/

没有自动跳转可以打开浏览器主动进入,就可以看到生成好的模板了。

资源下载: