今天我们介绍一个文档创建的工具-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/
没有自动跳转可以打开浏览器主动进入,就可以看到生成好的模板了。