mdbook
是一个简单好用的电子书、电子文档编写生成工具,我们可以使用Markdown语言编写文字内容,然后通过mdbook
工具将其预编译为HTML网站,部署在我们的静态服务器上。
曾经有一个非常好用的工具GitBook,包括Gitbook Editor
和一个基于Node的gitbook-cli
命令,它可以简化文档、电子书编写的工作流程,建立目录、编写文字、基于Git的版本控制、以web形式发布、输出为PDF等功能,都整合在这套工作流中,而且gitbook-cli
是完全开源的。在用途上,Gitbook设计上侧重于编写一本“书”,并非用于承载庞大冗杂的笔记系统,许多其它开源软件的文档都是基于Gitbook创建的。然而,这么好用的工具却被其开发团队搞死了,其团队商业化GitBook
服务,限制免费在线仓库数量,最为核心的开源gitbook-cli
直接不更新了,现在已无法使用。
而mdbook
正是曾经gitbook-cli
的另一个类似实现,mdbook
另一个优势是它用Rust语言编写,相比坑人的Node,不会出现若干年后因为依赖变动而无法运行的情况。
我们可以在其Github主页找到相关的预编译可执行文件:
https://github.com/rust-lang/mdBook
下载对应系统的可执行文件后,将其加入系统环境变量,我们即可在命令行中使用mdbook
命令。
创建一本书籍:
mdbook init <书名>
创建过程中会要求我们输入一些信息,执行过程如下:
创建完成后会自动生成一个新文件夹作为书籍的根目录。自动生成的目录结构例子如下:
testbook
|_book 编译输出目录
|_src 文档Markdown源文件目录
|_chapter_1.md
|_SUMMARY.md
|_book.toml 书籍配置文件
其中,book.toml
是本书的配置文件,内容包括书籍作者、语言等基本信息,我们可以根据需要自行修改。
我们编辑内容时,建议先编写目录,即SUMMARY.md
,例子如下:
# Summary
* [Introduction](README.md)
* [Chapter1](chapter1/README.md)
* [Note1](chapter1/note1.md)
* [Note2](chapter1/note2.md)
* [Chapter2](chapter2/README.md)
* [Note3](chapter2/note3.md)
* [Note4](chapter2/note4.md)
编写的内容其实就是标准的Markdown语法,其中包括了一组列表和链接。
在我们修改目录时,如果启动了预览服务器,我们对目录的修改会自动触发对应文件的创建。比如我们指定了目录chapter1/README.md
,相关的文件夹和Markdown文件会自动创建出来。
注意:删除目录则不会触发文件的自动删除,这是为了避免误删内容,删除操作时需要我们手动进行处理。
在书籍根目录执行如下命令即可启动预览服务:
mdbook serve
我们可以通过浏览器进行访问。
注意:我们对源文件内容的修改都会触发预览服务的自动编译更新。
当我们编写完成需要发布时,可以执行如下命令生成站点静态文件。
mdbook build
静态站点文件会输出到book
目录,注意如果使用版本控制系统,没必要将构建生成的book
文件夹中的内容提交,自动创建的.gitignore
文件已经申明这一点了。构建完成后,我们直接将其拷贝到服务器上即可访问,下面是部署到nginx的配置文件例子。
server {
listen 8080;
location / {
root /usr/share/nginx/html;
index index.html index.htm;
try_files $uri $uri/ /index.html;
expires 600s;
}
}
注意配置中我们指定了expires 600s
,该配置指定了mdbook
的缓存有效期,如果不指定该配置,可能出现书籍内容的缓存访问一次后永远也不会更新的状况。实际使用中,我们应该根据具体使用场景指定该有效期。