mdBook 特定功能
隐藏代码行
mdBook 中有一个功能可以让你通过在代码行前面加上 #
来隐藏代码行,就像你在 Rustdoc 中所做的那样。
# fn main() {
let x = 5;
let y = 6;
println!("{}", x + y);
# }
会渲染成
fn main() { let x = 5; let y = 6; println!("{}", x + y); }
包含文件
使用以下语法,您可以将文件包含到您的书中:
{{#include file.rs}}
文件路径必须相对于当前源文件。
mdBook 会将包含的文件解释为 Markdown。
由于 include 命令通常用于插入代码片段和示例,因此您通常会用 ```
包裹该命令以显示文件内容而不解释它们。
```
{{#include file.rs}}
```
包含文件的一部分
通常您只需要文件的特定部分,例如 相关行举例。 我们支持四种不同的部分模式包括:
{{#include file.rs:2}}
{{#include file.rs::10}}
{{#include file.rs:2:}}
{{#include file.rs:2:10}}
第一个命令只包含文件 file.rs
的第二行。
第二个命令包括到第 10 行的所有行,即从 11 到文件末尾的行被省略。
第三个命令包括第 2 行的所有行,即省略第一行。
最后一个命令包括 file.rs
的摘录,由第 2 行到第 10 行组成。
为了避免在修改包含的文件时破坏您的书籍,您还可以使用锚点而不是行号来包含特定部分。
锚点是一对匹配的线。 锚点开始的行必须与正则表达式 ANCHOR:\s*[\w_-]+
匹配,类似地,结束行必须与正则表达式 ANCHOR_END:\s*[\w_-]+
匹配。
这允许您在任何类型的注释行中放置锚点。
考虑包含以下文件:
/* ANCHOR: all */
// ANCHOR: component
struct Paddle {
hello: f32,
}
// ANCHOR_END: component
////////// ANCHOR: system
impl System for MySystem { ... }
////////// ANCHOR_END: system
/* ANCHOR_END: all */
然后在书中,你所要做的就是:
Here is a component:
```rust,no_run,noplayground
{{#include file.rs:component}}
```
Here is a system:
```rust,no_run,noplayground
{{#include file.rs:system}}
```
This is the full file.
```rust,no_run,noplayground
{{#include file.rs:all}}
```
包含在锚点内的锚点匹配模式的行将被忽略。
包含一个文件,但隐藏最初指定行之外的所有内容
rustdoc_include
helper 用于包含来自外部 Rust 文件的代码,这些文件包含完整的示例,但最初仅以与 include
相同的方式显示用行号或锚点指定的特定行。
不在行号范围内或锚点之间的行仍将包含在内,但它们将以 #
开头。 这样,读者可以展开代码片段以查看完整示例,而 Rustdoc 将在您运行 mdbook test
时使用完整示例。
例如,考虑一个名为 file.rs
的文件,其中包含这个 Rust 程序:
fn main() { let x = add_one(2); assert_eq!(x, 3); } fn add_one(num: i32) -> i32 { num + 1 }
我们可以使用以下语法包含一个最初仅显示第 2 行的代码段:
调用 `add_one` 函数, 我们传入一个 `i32` 并且将返回值赋值给 `x`:
```rust
{{#rustdoc_include file.rs:2}}
```
这与我们手动插入代码并使用#
隐藏除第 2 行之外的所有代码具有相同的效果:
调用 `add_one` 函数, 我们传入一个 `i32` 并且将返回值赋值给 `x`:
```rust
# fn main() {
let x = add_one(2);
# assert_eq!(x, 3);
# }
#
# fn add_one(num: i32) -> i32 {
# num + 1
# }
```
也就是说,它看起来像这样(单击“expand”图标以查看文件的其余部分):
fn main() { let x = add_one(2); assert_eq!(x, 3); } fn add_one(num: i32) -> i32 { num + 1 }
插入可运行的 Rust 文件
使用以下语法,您可以将可运行的 Rust 文件插入到您的书中:
{{#playground file.rs}}
Rust 文件的路径必须相对于当前源文件。
当点击 play 时,代码片段将被发送到 Rust Playground 进行编译和运行。 结果被送回并直接显示在代码下方。
下面是渲染的代码片段的样子:
fn main() { println!("Hello World!"); // You can even hide lines! :D println!("I am hidden! Expand the code snippet to see me"); }
控制页面 <title>
A chapter can set a <title> that is different from its entry in the table of contents (sidebar) by including a {{#title ...}}
near the top of the page.
通过在页面顶部附近包含一个{{#title ...}}
,章节可以设置一个<title>,该<title> 与其在目录(侧边栏)中的条目不同。
{{#title My Title}}