【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>
相关推荐
用户76855341255383 天前
文档站的截图和示例工程都塞进 Git 仓库后,我把素材托管重新理了一遍
markdown
木头左4 天前
【Node.js】Markdown 转带图片 Word 文档实战:docx 库转换器设计与 5 个踩坑
node.js·word·markdown·文档自动化
FungLeo7 天前
成为全栈·Vue 管理后台篇·编辑器图片上传:从文件选择到文章附件关联
前端·vue.js·编辑器·markdown·文件上传·formdata·附件管理
king王一帅10 天前
当 DSH 适配了 Quirekit md-editor: 你的笔记软件为何不能是 DSH(MIT开源)
agent·markdown·deepseek
用户2986985301412 天前
Python 实战:将 HTML 批量转换为 Markdown
python·html·markdown
喵喵匠13 天前
一份 Markdown 发十个平台:cspub 一稿多投
自动化·markdown·效率工具·仓颉·cli工具
IHaveADiscovery14 天前
无痛让AI由Markdown转Word:Pandoc模板了解一下
人工智能·word·markdown
用户2986985301417 天前
Python 将 Markdown 批量转为 HTML:单文件与目录遍历两种实现
python·html·markdown
树欲静·而风不止18 天前
许愿式编程:我把 Typability 改成了能日常顶替 Typora 的样子
ai·markdown
Frag0ut19 天前
Notepad++ 零基础入门:从记事本到代码编辑器的平滑过渡(2026最新版)
python·编辑器·html·json·notepad++·markdown·记事本