【mdBook】5.5 mdBook 特色功能

隐藏代码行

mdBook 提供了一项功能，可以通过在代码行前添加特定前缀来隐藏它们。

Rust 语言隐藏规则

对于 Rust 语言，可以在行首添加 # （# 后跟空格）来隐藏代码行，这与 Rustdoc 的行为一致。可以使用 ## 来转义前缀，防止以字面量 # 开头的行被隐藏。

rust 复制代码

# fn main() {
    let x = 5;
    let y = 6;

    println!("{}", x + y);
# }

渲染效果：

rust 复制代码

    let x = 5;
    let y = 6;

    println!("{}", x + y);

当点击或将鼠标悬停在代码块上时，会出现一个眼睛图标 ()，用于切换隐藏行的可见性。

自定义语言前缀

默认情况下，此功能仅适用于标记为 rust 的代码示例。但您可以在 book.toml 中为其他语言定义自定义前缀：

toml 复制代码

[output.html.code.hidelines]
python = "~"

前缀将隐藏任何以给定前缀开头的行。使用上面的 Python 前缀：

python 复制代码

~hidden()
nothidden():
~    hidden()
    ~hidden()
    nothidden()

渲染效果：

python 复制代码

nothidden():
    nothidden()

局部覆盖前缀

可以使用不同的前缀在局部覆盖此行为：

python,hidelines=!!! 复制代码

!!!hidden()
nothidden():
!!!    hidden()
    !!!hidden()
    nothidden()

Rust Playground

Rust 语言代码块会自动获得一个运行按钮 ()，点击后会执行代码并在代码块下方显示输出。这是通过将代码发送到 Rust Playground 实现的。

rust 复制代码

println!("Hello, World!");

如果没有 main 函数，代码会自动被包装在一个 main 函数中。

禁用运行按钮

要为特定代码块禁用运行按钮：

rust,noplayground 复制代码

let mut name = String::new();
std::io::stdin().read_line(&mut name).expect("failed to read line");
println!("Hello {}!", name);

要为所有代码块禁用运行按钮：

toml 复制代码

[output.html.playground]
runnable = false

Rust 代码块属性

在语言标识后可以包含以逗号、空格或制表符分隔的附加属性：

rust,ignore 复制代码

# 这个示例不会被测试
panic!("oops!");

这些属性在使用 mdbook test 测试 Rust 示例时特别重要，使用与 rustdoc 相同的属性，并有一些补充：

属性	描述
`editable`	启用编辑器
`noplayground`	移除运行按钮，但仍会被测试
`mdbook-runnable`	强制显示运行按钮，通常与 `ignore` 属性结合使用
`ignore`	不会被测试且不显示运行按钮，但仍以 Rust 语法高亮
`should_panic`	执行时应产生 panic
`no_run`	测试时编译但不运行，不显示运行按钮
`compile_fail`	代码应编译失败
`edition2015`/`edition2018`/`edition2021`/`edition2024`	强制使用特定的 Rust 版本

包含文件

使用以下语法可以将文件包含到您的书籍中：

handlebars 复制代码

{{#include file.rs}}

文件路径相对于当前源文件。

包含文件的部分内容

支持四种部分包含模式：

语法	描述
{``{#include file.rs:2}}	仅包含第 2 行
{``{#include file.rs::10}}	包含到第 10 行（包含）
{``{#include file.rs:2:}}	从第 2 行开始包含
{``{#include file.rs:2:10}}	包含第 2-10 行

使用锚点包含

可以使用锚点而不是行号来包含特定部分，避免修改包含文件时破坏书籍。

被包含文件：

rust 复制代码

/* ANCHOR: all */

// ANCHOR: component
struct Paddle {
    hello: f32,
}
// ANCHOR_END: component

////////// ANCHOR: system
impl System for MySystem { ... }
////////// ANCHOR_END: system

/* ANCHOR_END: all */

在书籍中使用：

handlebars 复制代码

这是一个组件：
```rust,no_run,noplayground
{{#include file.rs:component}}

这是一个系统：

rust,no_run,noplayground 复制代码

{{#include file.rs:system}}

这是完整文件：

rust,no_run,noplayground 复制代码

{{#include file.rs:all}}

复制代码

## 包含文件但初始只显示指定行

`rustdoc_include` 助手用于包含外部 Rust 文件中的完整示例，但初始只显示通过行号或锚点指定的行。

**示例文件** `file.rs`：
```rust
fn main() {
    let x = add_one(2);
    assert_eq!(x, 3);
}

fn add_one(num: i32) -> i32 {
    num + 1
}

使用方式：

handlebars 复制代码

要调用 `add_one` 函数，我们传递一个 `i32` 并将返回值绑定到 `x`：

```rust
{{#rustdoc_include file.rs:2}}

复制代码

**等效效果**：
```rust
# fn main() {
    let x = add_one(2);
#     assert_eq!(x, 3);
# }
#
# fn add_one(num: i32) -> i32 {
#     num + 1
# }

插入可运行的 Rust 文件

使用以下语法可以将可运行的 Rust 文件插入到书籍中：

handlebars 复制代码

{{#playground file.rs}}

Rust 文件的路径相对于当前源文件。

添加属性

在文件名后传递的任何附加值都将作为代码块的属性包含：

handlebars 复制代码

{{#playground example.rs editable}}

等效于：

rust,editable 复制代码

# example.rs 的内容在这里

控制页面标题

章节可以通过在页面顶部附近包含 {``{#title ...}} 来设置与目录（侧边栏）中条目不同的 <title>：

handlebars 复制代码

{{#title 我的标题}}

mdBook 提供的 HTML 类

左右浮动

class="left" 和 class="right"

html 复制代码

<img class="right" src="images/rust-logo-blk.svg" alt="Rust 徽标">

隐藏元素

class="hidden"

html 复制代码

<div class="hidden">这不会被看到。</div>

警告框

class="warning"

html 复制代码

<div class="warning">
这是一个需要您注意的问题。

警告框在文档中应谨慎使用，以避免"警告疲劳"，
即人们因为通常与他们的操作无关而习惯性忽略它们。
</div>