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/dir
epub
的排版相对于 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