mdbook 创建电子书

mdbook是一个简单好用的电子书、电子文档编写生成工具,我们可以使用Markdown语言编写文字内容,然后通过mdbook工具将其预编译为HTML网站,部署在我们的静态服务器上。

从gitbook到mdbook的历史

曾经有一个非常好用的工具GitBook,包括Gitbook Editor和一个基于Node的gitbook-cli命令,它可以简化文档、电子书编写的工作流程,建立目录、编写文字、基于Git的版本控制、以web形式发布、输出为PDF等功能,都整合在这套工作流中,而且gitbook-cli是完全开源的。在用途上,Gitbook设计上侧重于编写一本“书”,并非用于承载庞大冗杂的笔记系统,许多其它开源软件的文档都是基于Gitbook创建的。然而,这么好用的工具却被其开发团队搞死了,其团队商业化GitBook服务,限制免费在线仓库数量,最为核心的开源gitbook-cli直接不更新了,现在已无法使用。

mdbook正是曾经gitbook-cli的另一个类似实现,mdbook另一个优势是它用Rust语言编写,相比坑人的Node,不会出现若干年后因为依赖变动而无法运行的情况。

mdbook安装

我们可以在其Github主页找到相关的预编译可执行文件:

https://github.com/rust-lang/mdBook

下载对应系统的可执行文件后,将其加入系统环境变量,我们即可在命令行中使用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

我们可以通过浏览器进行访问。

注意:我们对源文件内容的修改都会触发预览服务的自动编译更新。

编译为Web站点并部署

当我们编写完成需要发布时,可以执行如下命令生成站点静态文件。

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的缓存有效期,如果不指定该配置,可能出现书籍内容的缓存访问一次后永远也不会更新的状况。实际使用中,我们应该根据具体使用场景指定该有效期。

作者:Gacfox
版权声明:本网站为非盈利性质,文章如非特殊说明均为原创,版权遵循知识共享协议CC BY-NC-ND 4.0进行授权,转载必须署名,禁止用于商业目的或演绎修改后转载。
Copyright © 2017-2024 Gacfox All Rights Reserved.
Build with NextJS | Sitemap