Mdbook电子书发布工具使用说明
使用要点
基本结构
tree -L 2 ─╯
.
├── README.md # 项目基本说明
├── bin # mdbook可执行文件
│ └── mdbook
├── book.toml # 书籍基本信息配置
├── mermaid-init.js # mermaid用到的js文件
├── mermaid.min.js # mermaid用到的js文件
├── mytheme # 书籍用到的主题
│ ├── FontAwesome
│ ├── ayu-highlight.css
│ ├── book.js
│ ├── clipboard.min.js
│ ├── css
│ ├── favicon.png
│ ├── favicon.svg
│ ├── fonts
│ ├── head.hbs
│ ├── header.hbs
│ ├── highlight.css
│ ├── highlight.js
│ ├── index.hbs
│ ├── mod.rs
│ ├── playground_editor
│ ├── redirect.hbs
│ ├── searcher
│ └── tomorrow-night.css
├── scripts # 一些文章里面提及的脚本文件
│ ├── anki_md_js
│ ├── gh-md-toc
│ ├── toc_generator.sh
│ ├── update_toc
│ └── update_toc_raw
├── smart-anchor.js
└── src # 书籍内容主体
├── SUMMARY.md # 目录页，唯一可以添加跳转的地方
├── app_deepin
├── app_extensions
├── app_plugin_list.md
├── imgs
├── macos_essentials.md
├── macos_ios_tips.md
├── overview.md
└── shortcuts_keymaps_config.md
13 directories, 29 files
Summary
要注意，mdbook中所有文章跳转链接只能放在Summary中。
图片资源与git lfs
git lfs使用场景
Git LFS 是 Github 开发的一个 Git 的扩展，用于实现 Git 对大文件的支持. 比如在游戏开发过程中,设计资源占用了很大一部分空间. 像png,psd等文件是二进制(blob) 的,体积也很庞大.但git的diff/patch等是基于文件行的.对于二进制文件来说. git需要存储每次commit的改动.每次当二进制文件修改,发生变化的时候. 都会产生额外的提交量.导致clone和pull的数据量大增.在线仓库的体积也会迅速增长.
LFS(Large File Storage) 就是为了解决这一问题而产生的工具.
- 它将你所标记的大文件保存至另外的仓库,而在主仓库仅保留其轻量级指针.
- 那么在你检出版本时,根据指针的变化情况下更新对应的大文件.而不是在本地保存所有版本的大文件
对mdbook的影响
因为mdbook默认是在src里面直接引用静态资源，所以如果用git lfs打开对应的资源存储就会导致发布后的github pages找不到静态资源。
Rust特供功能
隐藏代码行
fn main() { let x = 5; let y = 6; println!("{}", x + y); }
Rust Playground页面执行
默认支持
#![allow(unused)] fn main() { println!("Hello, World!"); }
指定不支持
let mut name = String::new();
std::io::stdin().read_line(&mut name).expect("failed to read line");
println!("Hello {}!", name);
包含文件自动渲染为md
全文件包含
```
{{#include ../../scripts/update_toc_raw}}
```
渲染后：
find . -type f -name '*.md' > temp
mds=`sort temp | uniq`
for md in $mds:
do
if echo $md | grep -q -E '\.md$'
then
echo $md
scripts/gh-md-toc --insert --no-backup $md
else
echo $md' not md'
fi
done
rm temp
指定行数
- 指定一行
```
{{#include ../../scripts/update_toc_raw:1}}
```
渲染后：
find . -type f -name '*.md' > temp
- 指定一行开始
```
{{#include ../../scripts/update_toc_raw:1:}}
```
渲染后：
find . -type f -name '*.md' > temp
mds=`sort temp | uniq`
for md in $mds:
do
if echo $md | grep -q -E '\.md$'
then
echo $md
scripts/gh-md-toc --insert --no-backup $md
else
echo $md' not md'
fi
done
rm temp
- 指定范围
```
{{#include ../../scripts/update_toc_raw:1:5}}
```
渲染后：
find . -type f -name '*.md' > temp
mds=`sort temp | uniq`
for md in $mds:
do
if echo $md | grep -q -E '\.md$'
- 指定到某行
```
{{#include ../../scripts/update_toc_raw::6}}
```
渲染后：
find . -type f -name '*.md' > temp
mds=`sort temp | uniq`
for md in $mds:
do
if echo $md | grep -q -E '\.md$'
then
指定锚点部分
打开行数
[output.html.playground]
editable = false # allows editing the source code
copyable = true # include the copy button for copying code snippets
copy-js = true # includes the JavaScript for the code editor
line-numbers = false # displays line numbers for editable code
runnable = true # displays a run button for rust code
line-numbers Display line numbers on editable sections of code. Requires both editable and copy-js to be true. Defaults to false.
插入代码
插入可运行代码: 只支持rust
页面直接编辑代码: *, editable
mdbook主题修改
基本页面介绍
tree mytheme -L 1 ─╯
mytheme
├── FontAwesome
├── ayu-highlight.css
├── book.js
├── clipboard.min.js
├── css
├── favicon.png
├── favicon.svg
├── fonts
├── head.hbs
├── header.hbs
├── highlight.css
├── highlight.js
├── index.hbs
├── mod.rs
├── playground_editor
├── redirect.hbs
├── searcher
└── tomorrow-night.css
5 directories, 13 files
- index.hbs is the handlebars template.
- head.hbs is appended to the HTML section.
- header.hbs content is appended on top of every book page.
- css/ contains the CSS files for styling the book.
- css/chrome.css is for UI elements.
- css/general.css is the base styles.
- css/print.css is the style for printer output.
- css/variables.css contains variables used in other CSS files.
- book.js is mostly used to add client side functionality, like hiding / un-hiding the sidebar, changing the theme, …
- highlight.js is the JavaScript that is used to highlight code snippets, you should not need to modify this.
- highlight.css is the theme used for the code highlighting.
- favicon.svg and favicon.png the favicon that will be used. The SVG version is used by newer browsers.
mdbook高级用法
关于book
- 首先，这是mdbook serve/build之后生成的静态网站目录
- src，和Summary同级的目录，就是网站根目录
- src之外的内容不会被自动加入到book，所以无法访问。
- 这里有三个办法解决静态文件访问的问题：
- 生成book之后再复制进去，不过每次都需要重新复制
- 把静态文件放在src里面，将会自动复制进去
- 只对于js和css文件，可以用book的additional-css/js参数配置进去
关于mdbook serve panit-失败
这可能是由于本地电脑开了太多程序占用资源，mdbook serve资源不足，重启电脑可解决
关于主题修改(theme)
- 在book.toml指定主题路径
- 只有指定文件名才会被用来渲染网页
关于markdown table
可以添加preprocessor：mdbook-extended-markdown
- 其实就是类似ASCII渲染，所见即所得
- 每一行长度需要一致, 所以注意不要中英文混合
- 每一行之间要有分割线
```extended-markdown-table
| | Tool |
| |------------------|----------------------|-----------------------------------|
| | | Markdown Tables | Extended Markdown Tables |
| Feature |------------------|----------------------|-----------------------------------|
| Support | | | Horizontal | ✓ |
| | Merged cells | ✗ |-----------------|-----------------|
| | | | Vertical | ✓ |
```
```extended-markdown-table
| Macros | Define | Usage | note | Example |
|----------------------------|----------------------------------------------------------------|----------------------|--------|------------|
| Declarative Macro | #[macro_export]/macro_rules! macro_name{} | macro_name!() | | println! |
|----------------------------|----------------------------------------------------------------|----------------------|--------|------------|
| Function Macro | #[proc_macros]/pub fn macro_name | macro_name!() | | |
|----------------------------|----------------------------------------------------------------|----------------------|--------|------------|
| Derive Macro | #[proc_macros_derive(DeriveMacroName)]/pub fn other_fn_name | DeriveMacroName!() | | |
|----------------------------|----------------------------------------------------------------|----------------------|--------|------------|
| Attritubte Macro | | | | |
```
mdbook插件推荐
自动检查
MDBook Link-Check
Michael-F-Bryan/mdbook-linkcheck: A backend for mdbook which will check your links for you.
自动生成
global-search
mattico/global-search: Global search for a collection of MDBooks
mdbook-toc
badboy/mdbook-toc: A preprocessor for mdbook to add inline Table of Contents support.
mdbook-pagetoc: 添加页内侧边栏toc
JorelAli/mdBook-pagetoc: A page table of contents for mdBook
Chapter 1 - Sample
mdbook-open-on-gh
badboy/mdbook-open-on-gh: mdbook preprocessor to add a open-on-github link on every page
book-summary
Automatically creates a SUMMARY.md file for your book (
mdbook/gitbook)
dvogt23/book-summary: 📔Book auto-summary 🦀🖤 (gitbook/mdBook)
mdbook-suto-gen-summary
knightflower1989/mdbook-auto-gen-summary: mdbook auto-gen-summary
mdbook-transcheck
dalance/mdbook-transcheck: Checker for translated mdbook
mdbook-man
vv9k/mdbook-man: Generate manual pages from mdBooks!
mdbook-bookimport: 使用标记块引入其他文件内容
mdbook自带的include语法同时支持行数和标记来引入文件内容
md2tex
A small utility to convert markdown files to tex. Forked from md2pdf, with an added focus on mdbook conversions. Also with the goal of eventually contributing back upstream.
- Used by mdbook-latex to generate PDF’s.
lbeckman314/md2tex: A fork of tforgione’s awesome md2pdf library, catered for mdbook.
mdbook-checklist
ANSSI-FR/mdbook-checklist: mdbook preprocessor for generating checklists and indexes
mdbook-chapter-path: 可以用来生成面包屑导航
mdBook Tag
mdbook toc: 自动生成toc
- mdbook-toc - crates.io: Rust Package Registry
- badboy/mdbook-toc: A preprocessor for mdbook to add inline Table of Contents support.
cargo install mdbook-toc
mdbook-footnote: 可以用于生成引用内容
mdBook-template: 不需要，直接修改主题
trpl-zh-cn-pdf
me1ting/trpl-zh-cn-pdf: trpl-zh-cn的mdBook风格的pdf，带全书签
mdbook-cms: 自动生成Summary
this will also walk your mdbook src dir and generate the book summary in /path/to/your/mdbook/src/SUMMARY.md
AlongWY/mdbook-cms: A preprocessor bring cms to mdbook.
mdbook-open-on-gh: 添加打开github分支的功能
可以在页面底部添加对应源文件的超链接
mdbook-readme: 解决readme与index不一致的问题
mdbook-readme - crates.io: Rust Package Registry
mdbook-cmdrun: 提供强悍的终端执行功能
该插件内置了下列编译器，可以直接执行代码
- Shell
total 88K
drwxr-xr-x 4 runner docker 4.0K Nov 27 15:02 .
drwxr-xr-x 4 runner docker 4.0K Nov 27 15:02 ..
-rw-r--r-- 1 runner docker 1.2K Nov 27 15:02 IINA_deepin.md
drwxr-xr-x 2 runner docker 4.0K Nov 27 15:02 OmniGroups
-rw-r--r-- 1 runner docker 1.1K Nov 27 15:02 alfred.md
-rw-r--r-- 1 runner docker 23 Nov 27 15:02 app_deepin.md
-rw-r--r-- 1 runner docker 2.9K Nov 27 15:02 drafts.md
-rw-r--r-- 1 runner docker 716 Nov 27 15:02 goodnotes.md
-rw-r--r-- 1 runner docker 1.7K Nov 27 15:02 jetbrains_ide.md
drwxr-xr-x 2 runner docker 4.0K Nov 27 15:02 karabiner
-rw-r--r-- 1 runner docker 2.1K Nov 27 15:02 marginnote_deepin.md
-rw-r--r-- 1 runner docker 27K Nov 27 15:02 mdbook_deepin.md
-rw-r--r-- 1 runner docker 238 Nov 27 15:02 picGo_deepin.md
-rw-r--r-- 1 runner docker 611 Nov 27 15:02 sigil_epub_editor.md
-rw-r--r-- 1 runner docker 2.5K Nov 27 15:02 tampermonkey.md
-rw-r--r-- 1 runner docker 677 Nov 27 15:02 typora_deepin.md
- Bash Script
<!-- cmdrun ../../materials/cmdrun/script.sh>
- Python3
Generated subtitle
This comes from the script.py file
Since I’m at in a scripting language,
I can compute whatever I want
- Rust
#![allow(unused)] fn main() { / < / ! / - / - / cmdrun cmdrun/script.rs - -> }
配置与替换
mdbook-fluent: 可以用配置文件进行整理
fluent主要是用来本地化配置
- book.toml可以用dir参数配置查找fluent文件的目录路径
- 目前暂未试验成功
\{\{\#\fluent ../../../materials/global.motto}}
\{\{\#\fluent global.hello}}
mdbook-variables: 在book.toml配置全局变量
# book.toml
[preprocessor.variables.variables]
motto = "保持批判，有所取舍，知行合一，方见真我"
# here
\{\{motto}}
保持批判，有所取舍，知行合一，方见真我
mdbook-regex: 对内容进行正则替换
可以看作是mdbook-variables的升级版
绘图
mdBook Graphviz: 支持graphviz的dot语言
https://github.com/badboy/mdbook-open-on-gh)
svgbob plugin for mdbook
boozook/mdbook-svgbob: SvgBob mdbook preprocessor which swaps code-blocks with neat SVG.
mdbook-skill-tree: 添加技能树渲染
mdbook-chart: 添加c3.js图表渲染功能
主要是通过添加额外js、css文件
mdbook-puml: plantuml渲染
不再使用，会导致markdown无法渲染表格;其功能可以被mdbook-kroki覆盖
比mdbook-plantuml更好用 mdbook-puml - crates.io: Rust Package Registry
绘图合集：kroki
IntelliPikchr: IDEA内置插件
Split editor with preview pane for .pikchr files, using kroki.io or self-hosted server for rendering
mdbook-kroki-preprocessor: 支持kroki渲染
kroki可以看作多种图表语言的统一接口
cargo install mdbook-kroki-preprocessor
自动渲染
mdbook-admonish
tommilligan/mdbook-admonish: A preprocessor for mdbook to add Material Design admonishments.
mdbook-curly-quotes
mdBook preprocessor that replaces straight quotes with curly quotes, except within code blocks or code spans. It does the same as the curly-quotes option of the mdBook HTML renderer. The only advantage is that it can be applied to any renderer. arminha/mdbook-curly-quotes: mdBook preprocessor that replaces straight quotes with curly quotes
mdbook-tera
基于tera模版引擎渲染 avitex/mdbook-tera: Tera preprocessor for mdBook Keats/tera: A template engine for Rust based on Jinja2/Django
sgoudham/mdbook-template
可以自定义页脚的图像
zjp-CN/mdbook-theme
提供更多主题自定义选项
- zjp-CN/mdbook-template: Yield a mdbook demo with mdbook-theme and a yml file for github action automation and page publication.
- mdbook-theme - crates.io: Rust Package Registry
mdbook-mark: 渲染高亮标签
blazood/mdbook-mark: this is a mdbook preprocessor which can render ==== to
mdbook-all-the-markdowns
bombsimon/mdbook-all-the-markdowns: 🗃️ Preprocessor for mdbook to render all the markdowns!
mdbook-wikilink
NOBLES5E/mdbook-wikilink: Support for wikilinks on mdBook.
mdbook-page-styles
ABCsOf/mdbook-page-styles: An mdbook preprocessor to apply styles to specific pages and elements.
mdbook-note
mdbook-section-validator
younata/mdbook-section-validator: mdBook preprocessor for defining conditionally valid sections
mdbook-quiz: 添加在线测验功能
cargo install mdbook-quiz
git clone https://github.com/willcrichton/mdbook-quiz
cd mdbook-quiz
cargo install --path .
配置方式
You can configure mdbook-quiz by adding options to the [preprocessor.quiz] section of book.toml. The options are:
- validate (boolean): If true, then mdbook-quiz will validate your quiz TOML files using the validator.js script installed with mdbook-quiz. You must have NodeJS installed on your machine and PATH for this to work.
- fullscreen (boolean): If true, then a quiz will take up the web page’s full screen during use.
- cache-answers (boolean): If true, then the user’s answers will be saved in their browser’s localStorage. Then the quiz will show the user’s answers even after they reload the page.
注意⚠️
- 该插件默认只是在src里面自动生成mdbook-quiz, 里面包含必须但js和css文件
- 默认情况下只能在src目录下生效，与mdbook-quiz同级。
- 目前改成直接从book.toml引入，就可以全局使用
- 注意引入测试文件的代码行上下需要为空行
\{\{\#\quiz ../../materials/quizzes/rust-variables.toml}}
\{\{\#\quiz ../../materials/quizzes/quiz.toml}}
题型说明
[[questions]]
type = "MultipleChoice"
prompt.prompt = "What does it mean if a variable `x` is immutable?"
prompt.choices = [
"`x` is stored in the immutable region of memory.",
"After being defined, `x` can be changed at most once.",
"`x` cannot be changed after being assigned to a value.",
"You cannot create a reference to `x`."
]
answer.answer = 2
context = """
Immutable means "not mutable", or not changeable.
"""
[[questions]]
type = "ShortAnswer"
prompt.prompt = "What is the keyword used after `let` to indicate that a variable can be mutated?"
answer.answer = "mut"
context = """
For example, you can make a mutable variable `x` by writing: `let mut x = 1`.
"""
[[questions]]
type = "Tracing"
prompt.program = """
fn main() {
let x = 1;
println!("{x}");
x += 1;
println!("{x}");
}
"""
answer.doesCompile = false
answer.lineNumber = 4
context = """
This is a compiler error because line 4 tries to mutate `x` when `x` is not marked as `mut`.
"""
{{#quiz ../../materials/quizzes/rust-variables.toml}}
{{#quiz ../../materials/quizzes/quiz.toml}}
其他格式
playscript: 戏剧脚本格式
unevil-rs: 与mdbook无关，只是单独用来写ppt
Gooseberry - a Knowledge Base for the Lazy
一个很棒的工具，可以直接将mdbook转为知识库
ppt: 可以切换ppt还是markdown
这个插件将html算是玩的比较深入
举例(windows-alt+p|osx-option+p切换)
An Interesting Thing
Press
alt+pto toggle which version is displayed. Open the console to see the notes printed there
Here is a much longer explanation about what this interesting thing is and how interesting you might find it.
To elaborate, it is extremely interesting.
A list of things
- Fact one is intriguing
- Fact two is piquing my interest
- Fact three has me down right flabbergasted
- Fact four is almost obscene
- web-only
-
Slides-only
-
notes
本地示例
这里是默认内容，web-only
这里是slides-only: 待完成内容
- Fact one is intriguing
- Fact two is piquing my interest
- Fact three has me down right flabbergasted
- Fact four is almost obscene