mdbook 实例教程：打包阮一峰最新电子书《TypeScript 教程》
阮一峰的博客是科技类博客中的佼佼者，内容丰富，排版精美，业界良心，访问量巨大。每周五的《科技爱好者周刊》更是备受关注与期待。作为阮一峰博客的拥趸和忠实读者，我迫不及待地盼望着每周五的到来，期待着能够在周刊中找到那些令人震撼的科技新闻与深度分析。同样，阮老师著译出版物质量都很高，其关于JavaScript的相关作品更是深入浅出，广受读者欢迎。
今天看到阮一峰老师的最新电子书TypeScript 教程 - 网道[1] 已经上线了，为了方便离线阅读，就用 mdbook 将其打包成 PDF 和 EPUB 格式。文末附下载。
mdbook
介绍 - mdBook 中文文档[2]
mdBook 是一个由 RUST 构建的命令行工具，可以将 Markdown 文档，变成 HTML 网站，可以用来制作电子书。这样的工具，用在产品信息或是 API 文档, 教程, 课件资料等等场景。
• 轻量级： Markdown[3] 语法
• 搜索： 集成 search[4] 功能
• 语法高亮： syntax highlighting[5]
• 多个主题： Theme[6] 自定义输出的格式
• 预先处理器： Preprocessors[7] 预处理的扩展，比如
• 后端： Backends[8] 选择输出的渲染格式
• 自然，还具有 Rust[9] 加持，速度杠杠的。
• 甚至，Rust 代码[10] 的自动测试。
安装
安装 mdbook 非常简单，在安装好RUST环境和工具链后，只需要执行下面的命令即可：
cargo install mdbook创建
如创建一个名为 tsbook 的电子书项目：
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::book::init): Creating a new book with stub content
All done, no errors...默认会创建一个 src 目录，里面有一个 SUMMARY.md 文件，用来存放目录结构。
📦tsbook
┣ 📂book
┣ 📂src
┃ ┣ 📜chapter_1.md
┃ ┗ 📜SUMMARY.md
┣ 📜.gitignore
┗ 📜book.toml其中，根目录下的 book.toml 是配置文件，可以用来配置电子书的标题、作者、语言、主题等信息。
[book]
authors = ["mzhren"]
language = "en"
multilingual = false
src = "src"
title = "a typescript book"src 目录下的 SUMMARY.md 是目录结构文件，用来配置电子书的目录结构。
# Summary
- [Chapter 1](./chapter_1.md)预览
mdbook serve打包
mdbook build这样就会在 book 目录下生成一个 index.html 文件，用浏览器打开即可，跟预览的效果一样，可以用来发布到网站上。
📦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
cargo install mdbook-pdf配置《TypeScript 教程》
下载《TypeScript 教程》的源码：
wangdoc/typescript-tutorial: TypeScript 教程[11]
用 mdbook 初始化已经创建了一个电子书项目，现在我们需要将《TypeScript 教程》的内容拷贝到 src 目录下。
设置好目录结构后，我们需要修改 SUMMARY.md 文件，将目录结构写入到 SUMMARY.md 文件中。
# 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 教程》的信息。
[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
mdbook build这样，pdf 文件就生成了。其默认路径是 book/pdf/output.pdf。
遗留问题
生成的 PDF 文件，没有目录（虽然安装了mdbook-pdf-outline ，但调用不到）。可能是我配置的问题，还需要进一步研究。
生成EPUB
mdbook 有一个实验性质的 mdbook-epub 后端渲染器，可以将 mdbook 生成的 HTML 文件，转换成 EPUB 格式。
安装 mdbook-epub
cargo install mdbook-epub只要在 book.toml 文件中添加 epub 配置，就可以生成 EPUB 文件了。
+ [output.epub]mdbook-epub 也可以单独使用，不需要 mdbook 来调用它，自己就可渲染出 EPUB 文件。如果只想渲染 EPUB 文档，这种方式非常有用。
$ mdbook-epub -s true ./path/to/book/dir
$ mdbook-epub --standalone true ./path/to/book/direpub 的排版相对于 pdf 来说，要复杂一些。而阮一峰老师这本书，写得十分规整，排版也很漂亮，也不涉及图片，所以生成的 epub 文件也非常漂亮。
PDF & EPUB 下载
https://www.aliyundrive.com/s/yEkXFFeqaph 提取码: wl94
链接：https://pan.baidu.com/s/1eiPaDjTwgjD4O1V_vU-Bzg?pwd=1234 提取码：1234
参考资料
• mdBook - mdBook Documentation[12]
• mdbook 写作真的好用 - 掘金[13]
• HollowMan6/mdbook-pdf: A backend for mdBook written in Rust for generating PDF based on headless chrome and Chrome DevTools Protocol. (用 Rust 编写的 mdBook 后端，基于headless chrome和Chrome开发工具协议生成PDF)[14]
• mdbook-pdf-outline · PyPI[15]
• mdbook-chapter-number — Rust application // Lib.rs[16]
• mdbook-pdf/README_CN.md at main · HollowMan6/mdbook-pdf[17]
• Michael-F-Bryan/mdbook-epub: An experimental mdbook backend for creating EPUB documents.[18]
往期推荐
欢迎关注我的公众号“码农真经”，原创技术文章第一时间推送。
引用链接
[1] TypeScript 教程 - 网道: https://wangdoc.com/typescript/[2] 介绍 - mdBook 中文文档: https://llever.com/mdBook-zh/[3] Markdown: https://llever.com/mdBook-zh/format/markdown.zh.html[4] search: https://llever.com/mdBook-zh/guide/reading.zh.html#search[5] syntax highlighting: https://llever.com/mdBook-zh/format/theme/syntax-highlighting.zh.html[6] Theme: https://llever.com/mdBook-zh/format/theme/index.html[7] Preprocessors: https://llever.com/mdBook-zh/format/configuration/preprocessors.zh.html[8] Backends: https://llever.com/mdBook-zh/format/configuration/renderers.zh.html[9] Rust: https://www.rust-lang.org/[10] Rust 代码: https://llever.com/mdBook-zh/cli/test.zh.html[11] wangdoc/typescript-tutorial: TypeScript 教程: https://github.com/wangdoc/typescript-tutorial[12] mdBook - mdBook Documentation: https://crisal.io/tmp/book-example/book/index.html[13] mdbook 写作真的好用 - 掘金: https://juejin.cn/post/7201787862236823608[14] HollowMan6/mdbook-pdf: A backend for mdBook written in Rust for generating PDF based on headless chrome and Chrome DevTools Protocol. (用 Rust 编写的 mdBook 后端，基于headless chrome和Chrome开发工具协议生成PDF): https://github.com/HollowMan6/mdbook-pdf[15] mdbook-pdf-outline · PyPI: https://pypi.org/project/mdbook-pdf-outline/[16] mdbook-chapter-number — Rust application // Lib.rs: https://lib.rs/crates/mdbook-chapter-number[17] mdbook-pdf/README_CN.md at main · HollowMan6/mdbook-pdf: https://github.com/HollowMan6/mdbook-pdf/blob/main/README_CN.md[18] Michael-F-Bryan/mdbook-epub: An experimental mdbook backend for creating EPUB documents.: https://github.com/Michael-F-Bryan/mdbook-epub