备用后端
“后端“只是一个，mdbook在书籍渲染过程中调用的程序。该程序会拿到传递到stdin的书籍和配置信息的 JSON 表达式。一旦后端收到这些信息,就可以自由地做任何想做的事情.
Configuring Renderers 有更多信息。
社区也开发了几个后端 [Third Party Plugins]
目录
设置好
此页面将引导您，创建自己的单词计数程序的简单形式的备用后端。虽然它将用 Rust 编写，但没有理由不能用 Python 或 Ruby 之类，来完成它。
首先，您需要创建一个新的二进制程序，并添加mdbook作为依赖.
$ cargo new --bin mdbook-wordcount
$ cd mdbook-wordcount
$ cargo add mdbook
捋一捋，当我们的mdbook-wordcount插件被调用，mdbook将通过我们的插件的stdin，发送它RenderContext的 JSON 版本。为方便起见，有一个RenderContext::from_json()构造函数，加载一个RenderContext。
这是我们后端加载本书，所需的所有样板.
// src/main.rs extern crate mdbook; use std::io; use mdbook::renderer::RenderContext; fn main() { let mut stdin = io::stdin(); let ctx = RenderContext::from_json(&mut stdin).unwrap(); }
注意:
RenderContext包含一个version字段。这使得后端在被调用时确定它们是否与mdbook版本兼容。这个version直接来自mdbook的Cargo.toml中的相应字段.
建议后端使用semver，如果可能存在兼容性问题,请检查此字段，并发出警告.
检查 Book
现在我们的后端有一本书的副本,让我们计算每章中有多少单词!
因为RenderContext包含一个Book字段(book),和一个Book有Book::iter()，用于迭代其Book中所有项的方法，这一步就和第一步一样简单.
fn main() { let mut stdin = io::stdin(); let ctx = RenderContext::from_json(&mut stdin).unwrap(); for item in ctx.book.iter() { if let BookItem::Chapter(ref ch) = *item { let num_words = count_words(ch); println!("{}: {}", ch.name, num_words); } } } fn count_words(ch: &Chapter) -> usize { ch.content.split_whitespace().count() }
启用吧，我的 Backend
现在我们的基本部分已经运行了，我们希望实际使用它。那首先,当然是安装程序.
$ cargo install --path .
然后cd在特定的书目录中，若你想要数字计数，那更新它的book.toml文件.
[book]
title = "mdBook Documentation"
description = "Create book from markdown files. Like Gitbook but implemented in Rust"
authors = ["Mathieu David", "Michael-F-Bryan"]
+ [output.html]
+ [output.wordcount]
当mdbook将一本书加载到内存中时，它会尝试检查你的book.toml，并查找所有output.*表格来尝试找出要使用的后端。如果没有提供，它将回退到，使用默认的 HTML 渲染器.
值得注意的是，这表示如果你想添加自己的自定义后端，你还需要确保添加 HTML 后端，即使只是空表格。
现在你只需要像平常一样构建你的书，一切都应该 可以工作。
$ mdbook build
...
2018-01-16 07:31:15 [INFO] (mdbook::renderer): Invoking the "mdbook-wordcount" renderer
mdBook: 126
Command Line Tool: 224
init: 283
build: 145
watch: 146
serve: 292
test: 139
Format: 30
SUMMARY.md: 259
Configuration: 784
Theme: 304
index.hbs: 447
Syntax highlighting: 314
MathJax Support: 153
Rust code specific features: 148
For Developers: 788
Alternative Backends: 710
Contributors: 85
我们之所以不需要指定我们wordcount后端的全名/路径，是因为mdbook会尽力的推断程序的名称，这些都是因为规范化，如下: 可执行文件foo后端通常被称为mdbook-foo，还有相关联的[output.foo]会进入book.toml。而要明确告诉mdbook要调用什么命令(可能需要命令行参数或是解释的脚本)， 你可以使用command字段。
[book]
title = "mdBook Documentation"
description = "Create book from markdown files. Like Gitbook but implemented in Rust"
authors = ["Mathieu David", "Michael-F-Bryan"]
[output.html]
[output.wordcount]
+ command = "python /path/to/wordcount.py"
配置
现在假设您不想计算特定章节上的单词数(可能是生成的文本/代码等)。要做到这样的规范方法，是通过常规book.toml配置文件，添加个别项到您的[output.foo]表格。
Config可以粗略地视为嵌套的hashmap，它允许您调用类似的方法get()使用访问配置的内容，也带get_deserialized()这一方便方法,用于检索值，并自动反序列化为某种任意类型T.
为实现这一点,我们将创建自己的可序列化WordcountConfig结构将封装此后端的所有配置.
首先添加serde和serde_derive到你的Cargo.toml,
$ cargo add serde serde_derive
然后你可以创建配置结构,
#![allow(unused)] fn main() { extern crate serde; #[macro_use] extern crate serde_derive; ... #[derive(Debug, Default, Serialize, Deserialize)] #[serde(default, rename_all = "kebab-case")] pub struct WordcountConfig { pub ignores: Vec<String>, } }
现在我们只需要我们的RenderContext，反序列化成WordcountConfig，然后添加一个检查，以确保我们跳过忽略的章节。
fn main() {
let mut stdin = io::stdin();
let ctx = RenderContext::from_json(&mut stdin).unwrap();
+ let cfg: WordcountConfig = ctx.config
+ .get_deserialized("output.wordcount")
+ .unwrap_or_default();
for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item {
+ if cfg.ignores.contains(&ch.name) {
+ continue;
+ }
+
let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words);
}
}
}
输出和信号故障
虽然在构建书籍时，将字数计数打印到终端是很好的，但将它们输出到某个文件也可能是个好主意。mdbook能告诉后端，它应该根据RenderContext的destination字段，放置输出的位置，.
+ use std::fs::{self, File};
+ use std::io::{self, Write};
- use std::io;
use mdbook::renderer::RenderContext;
use mdbook::book::{BookItem, Chapter};
fn main() {
...
+ let _ = fs::create_dir_all(&ctx.destination);
+ let mut f = File::create(ctx.destination.join("wordcounts.txt")).unwrap();
+
for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item {
...
let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words);
+ writeln!(f, "{}: {}", ch.name, num_words).unwrap();
}
}
}
注意: 无法保证目标目录存在或为空(
mdbook可能会留下以前的内容让后端进行缓存)，因此创建它fs::create_dir_all()总不会错。如果目的地目录已存在, 不要假设它就一定是空的。 要知道，后端是有上一结果缓存的,
mdbook或许会留下 旧的内容在里面。
处理书籍时，总会出现错误(只需查看全部我们已经写过了的unwrap())吗，所以mdbook会渲染失败后，非零退出代码。
例如，如果我们想确保所有章节的单词，都有偶数数量， 而如果遇到奇数，则输出错误，那么你可以这样做:
+ use std::process;
...
fn main() {
...
for item in ctx.book.iter() {
if let BookItem::Chapter(ref ch) = *item {
...
let num_words = count_words(ch);
println!("{}: {}", ch.name, num_words);
writeln!(f, "{}: {}", ch.name, num_words).unwrap();
+ if cfg.deny_odds && num_words % 2 == 1 {
+ eprintln!("{} has an odd number of words!", ch.name);
+ process::exit(1);
}
}
}
}
#[derive(Debug, Default, Serialize, Deserialize)]
#[serde(default, rename_all = "kebab-case")]
pub struct WordcountConfig {
pub ignores: Vec<String>,
+ pub deny_odds: bool,
}
现在，如果我们重新安装后端，并构建一本书,
$ cargo install --path . --force
$ mdbook build /path/to/book
...
2018-01-16 21:21:39 [INFO] (mdbook::renderer): Invoking the "wordcount" renderer
mdBook: 126
Command Line Tool: 224
init: 283
init has an odd number of words!
2018-01-16 21:21:39 [ERROR] (mdbook::renderer): Renderer exited with non-zero return code.
2018-01-16 21:21:39 [ERROR] (mdbook::utils): Error: Rendering failed
2018-01-16 21:21:39 [ERROR] (mdbook::utils): Caused By: The "mdbook-wordcount" renderer failed
您可能已经注意到，插件的子进程的输出会立即传递给用户。鼓励插件遵循“安静规则“，且仅在必要时生成输出(例如，生成错误或警告)。
所有环境变量都传递到后端，允许您使用常用的RUST_LOG，控制日志记录详细程度.
包涵包涵
虽然有点做作，但希望这个例子足以说明，如何创建一个mdbook备用后端。如果你觉得它遗漏了什么，请不要犹豫，创造一个问题的issue tracker，让我们可以一起改进用户指南。
在本章开头提到的现有后端，应该是现实生活中如何完成后端的很好例子，所以请随意浏览源代码，或提出问题.