mdbook 实例教程：打包阮一峰最新电子书《TypeScript 教程》

阮一峰的博客是科技类博客中的佼佼者，内容丰富，排版精美，业界良心，访问量巨大。每周五的《科技爱好者周刊》更是备受关注与期待。作为阮一峰博客的拥趸和忠实读者，我迫不及待地盼望着每周五的到来，期待着能够在周刊中找到那些令人震撼的科技新闻与深度分析。同样，阮老师著译出版物质量都很高，其关于JavaScript的相关作品更是深入浅出，广受读者欢迎。

今天看到阮一峰老师的最新电子书TypeScript 教程 - 网道已经上线了，为了方便离线阅读，就用 mdbook 打包成 PDF 和 EPUB 格式。文末附下载。

mdbook

介绍 - mdBook 中文文档

mdBook 是一个由 RUST 构建的命令行工具，可以将 Markdown 文档，变成 HTML 网站，可以用来制作电子书。这样的工具，用在产品信息或是 API 文档, 教程, 课件资料等等场景。

轻量级： Markdown 语法
搜索： 集成 search 功能
语法高亮： syntax highlighting
多个主题： Theme 自定义输出的格式
预先处理器： Preprocessors 预处理的扩展，比如
后端： Backends 选择输出的渲染格式
自然，还具有 Rust 加持，速度杠杠的。
甚至，Rust 代码的自动测试。

安装

安装 mdbook 非常简单，在安装好RUST环境和工具链后，只需要执行下面的命令即可：

1

cargo install mdbook

创建

如创建一个名为 tsbook 的电子书项目：

mdbook init

1
2
3
4
5
6
7
8
9


PS C:\projects\online-books> mdbook init tsbook

Do you want a .gitignore to be created? (y/n)
y
What title would you like to give the book?
a typescript book
2023-08-08 23:34:37 [INFO] (mdbook:📖:init): Creating a new book with stub content

All done, no errors...

默认会创建一个 src 目录，里面有一个 SUMMARY.md 文件，用来存放目录结构。

1
2
3
4
5
6
7


📦tsbook
 ┣ 📂book
 ┣ 📂src
 ┃ ┣ 📜chapter_1.md
 ┃ ┗ 📜SUMMARY.md
 ┣ 📜.gitignore
 ┗ 📜book.toml

其中，根目录下的 book.toml 是配置文件，可以用来配置电子书的标题、作者、语言、主题等信息。

1
2
3
4
5
6


[book]
authors = ["mzhren"]
language = "en"
multilingual = false
src = "src"
title = "a typescript book"

src 目录下的 SUMMARY.md 是目录结构文件，用来配置电子书的目录结构。

1
2
3


# Summary

- [Chapter 1](./chapter_1.md)

预览

1

mdbook serve

mdbook serve

打包

1

mdbook build

这样就会在 book 目录下生成一个 index.html 文件，用浏览器打开即可，跟预览的效果一样，可以用来发布到网站上。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55


📦tsbook
 ┣ 📂book
 ┃ ┣ 📂css
 ┃ ┃ ┣ 📜chrome.css
 ┃ ┃ ┣ 📜general.css
 ┃ ┃ ┣ 📜print.css
 ┃ ┃ ┗ 📜variables.css
 ┃ ┣ 📂FontAwesome
 ┃ ┃ ┣ 📂css
 ┃ ┃ ┃ ┗ 📜font-awesome.css
 ┃ ┃ ┗ 📂fonts
 ┃ ┃ ┃ ┣ 📜fontawesome-webfont.eot
 ┃ ┃ ┃ ┣ 📜fontawesome-webfont.svg
 ┃ ┃ ┃ ┣ 📜fontawesome-webfont.ttf
 ┃ ┃ ┃ ┣ 📜fontawesome-webfont.woff
 ┃ ┃ ┃ ┣ 📜fontawesome-webfont.woff2
 ┃ ┃ ┃ ┗ 📜FontAwesome.ttf
 ┃ ┣ 📂fonts
 ┃ ┃ ┣ 📜fonts.css
 ┃ ┃ ┣ 📜OPEN-SANS-LICENSE.txt
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-300.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-300italic.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-600.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-600italic.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-700.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-700italic.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-800.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-800italic.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-italic.woff2
 ┃ ┃ ┣ 📜open-sans-v17-all-charsets-regular.woff2
 ┃ ┃ ┣ 📜SOURCE-CODE-PRO-LICENSE.txt
 ┃ ┃ ┗ 📜source-code-pro-v11-all-charsets-500.woff2
 ┃ ┣ 📜.nojekyll
 ┃ ┣ 📜404.html
 ┃ ┣ 📜ayu-highlight.css
 ┃ ┣ 📜book.js
 ┃ ┣ 📜chapter_1.html
 ┃ ┣ 📜clipboard.min.js
 ┃ ┣ 📜elasticlunr.min.js
 ┃ ┣ 📜favicon.png
 ┃ ┣ 📜favicon.svg
 ┃ ┣ 📜highlight.css
 ┃ ┣ 📜highlight.js
 ┃ ┣ 📜index.html
 ┃ ┣ 📜mark.min.js
 ┃ ┣ 📜print.html
 ┃ ┣ 📜searcher.js
 ┃ ┣ 📜searchindex.js
 ┃ ┣ 📜searchindex.json
 ┃ ┗ 📜tomorrow-night.css
 ┣ 📂src
 ┃ ┣ 📜chapter_1.md
 ┃ ┗ 📜SUMMARY.md
 ┣ 📜.gitignore
 ┗ 📜book.toml

生成PDF

生成PDF的方法有很多种，比如用浏览器打印，或者用Pandoc等工具。mdbook 有一个 mdbook-pdf 项目，可以将 mdbook 生成的 HTML 文件，转换成 PDF 格式。

mdbook-pdf 有两种生成 PDF 的方式：

通过浏览器打印功能，将 HTML 文件转换成 PDF 文件。
通过 wkhtmltopdf 工具，将 HTML 文件转换成 PDF 文件。

安装 mdbook-pdf

1

cargo install mdbook-pdf

配置《TypeScript 教程》

下载《TypeScript 教程》的源码：

wangdoc/typescript-tutorial: TypeScript 教程

用 mdbook 初始化已经创建了一个电子书项目，现在我们需要将《TypeScript 教程》的内容拷贝到 src 目录下。

设置好目录结构后，我们需要修改 SUMMARY.md 文件，将目录结构写入到 SUMMARY.md 文件中。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# Summary

- [简介](./intro.md)
- [基本用法](./basic.md)
- [any 类型](./any.md)
- [类型系统](./types.md)
- [数组](./array.md)
- [元组](./tuple.md)
- [symbol 类型](./symbol.md)
- [函数](./function.md)
- [对象](./object.md)
- [interface](./interface.md)
- [类](./class.md)
- [泛型](./generics.md)
- [Enum 类型](./enum.md)
- [类型断言](./assert.md)
- [模块](./module.md)
- [namespace](./namespace.md)
- [装饰器](./decorator.md)
- [装饰器（旧语法）](./decorator-legacy.md)
- [declare 关键字](./declare.md)
- [d.ts 类型声明文件](./d.ts.md)
- [运算符](./operator.md)
- [类型映射](./mapping.md)
- [类型工具](./utility.md)
- [注释指令](./comment.md)
- [tsconfig.json 文件](./tsconfig.json.md)
- [tsc 命令](./tsc.md)

更改 toml 文件，将电子书的标题、作者、语言、主题等信息修改成《TypeScript 教程》的信息。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


[book]
authors = ["阮一峰"]
language = "zh-CN"
multilingual = false
src = "src"
title = "阮一峰《TypeScript 教程》"

# 添加章节序号
[preprocessor.chapter-number]

# 导出 html、pdf、带目录的pdf
[output.html]
[output.pdf]

# 添加页眉页脚
display-header-footer= true
header-template = "<h3 style='font-size:8px; margin-left: 85px;width:200px;' class='title'></h3><h3 style='margin-left:120px;font-size:8px;'>https://wangdoc.com/typescript/</h3>"
footer-template = "<p style='font-size:10px; margin-left: 48%'><span class='pageNumber'></span> / <span class='totalPages'></span></p>"
prefer-css-page-size = true

[output.pdf-outline]
optional = true

生成PDF

1

mdbook build

这样，pdf 文件就生成了。其默认路径是 book/pdf/output.pdf。

遗留问题

生成的 PDF 文件，没有目录（虽然安装了mdbook-pdf-outline ，但调用不到）。可能是我配置的问题，还需要进一步研究。

生成EPUB

mdbook 有一个实验性质的 mdbook-epub 后端渲染器，可以将 mdbook 生成的 HTML 文件，转换成 EPUB 格式。

安装 mdbook-epub

1

cargo install mdbook-epub

只要在 book.toml 文件中添加 epub 配置，就可以生成 EPUB 文件了。

1
2

+ [output.epub]

mdbook-epub 也可以单独使用，不需要 mdbook 来调用它，自己就可渲染出 EPUB 文件。如果只想渲染 EPUB 文档，这种方式非常有用。

1
2


$ mdbook-epub -s true ./path/to/book/dir
$ mdbook-epub --standalone true ./path/to/book/dir

epub 的排版相对于 pdf 来说，要复杂一些。而阮一峰老师这本书，写得十分规整，排版也很漂亮，也不涉及图片，所以生成的 epub 文件也非常漂亮。

PDF & EPUB 下载

https://www.aliyundrive.com/s/yEkXFFeqaph
提取码: wl94

链接：https://pan.baidu.com/s/1eiPaDjTwgjD4O1V_vU-Bzg?pwd=1234
提取码：1234