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}}

mdBook 文档