Windows/Linux/Macos

安装方式

1、cargo 主版本安装：

1
cargo install --git https://github.com/rust-lang/mdBook.git mdbook

2、源码安装

安装：

1
cargo install mdbook

这将自动从 crates.io 下载 mdBook，构建它，并将其安装在 Cargo 的全局二进制目录中（ ~/.cargo/bin/默认）。

卸载：

1
cargo uninstall mdbook

同样，确保将 Cargo bin 目录添加到您的 PATH.

3、github 下载

https://github.com/rust-lang/mdBook/releases

同上，配置环境变量。

基础使用

使用”mdbook init”命令创建一本书：

1
mdbook init <directory>

在生成这本书之前，它会问几个问题。 回答完问题后，您可以将当前目录更改为新书：

mdbook-init

有几种方法可以渲染一本书，但最简单的方法之一是使用 serve命令，它将构建您的书并启动本地网络服务器：

1
mdbook serve --open (缩写：-o)

–open ：将打开您的默认网络浏览器以查看您的新书。 即使在编辑书籍内容时，您也可以让服务器保持运行状态，并且 mdbook将自动重建输出，并自动刷新您的网络浏览器。

结构

一本书由几个文件组成，这些文件定义了书籍的设置和布局。

book.toml

在书的根部，有一个 book.toml文件，其中包含用于描述如何构建图书的设置。 这是用 TOML 标记语言 。 默认设置通常足以让您入门。

1
2
3
# 示例
[book]
title= "My First Book"

SUMMARY.md

一本书的下一个主要部分是摘要文件，位于 src/SUMMARY.md. 该文件包含本书所有章节的列表。 在查看章节之前，必须将其添加到此列表中。

这是一个包含几章的基本摘要文件：

1
2
3
4
5
6
7
# 示例：

# Summary
[Introduction](README.md)
- [My First Chapter](my-first-chapter.md)
- [Nested example](nested/README.md)
    - [Sub-chapter](nested/sub-chapter.md)

尝试打开 src/SUMMARY.md在您的编辑器中并添加几章。 如果任何章节文件不存在， mdbook将自动为您创建它们。

源文件

你的书的内容都包含在 src目录。 每章都是一个单独的 Markdown 文件。 通常，每个章节都以带有章节标题的 1 级标题开始。

1
2
3
#示例：	
	# My First Chapter
	Fill out your content here.

文件的精确布局取决于您。 文件的组织将与生成的 HTML 文件相对应，因此请记住，文件布局是每章 URL 的一部分。

虽然 mdbook serve命令正在运行，您可以打开任何章节文件并开始编辑它们。 每次保存文件时， mdbook将重建这本书并刷新您的网络浏览器。

src目录将包含在输出中。 因此，如果您有图像或其他静态文件，只需将它们包含在 src目录。

发布一本书

写完书后，您可能希望将其托管在某个地方以供其他人查看。 第一步是构建本书的输出。 这可以在book.toml同一目录中使用“mdbook build”命令构建

这将生成一个名为 book其中包含您图书的 HTML 内容。 然后，您可以将此目录放在任何 Web 服务器上以托管它。

命令行工具

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
mdbook help —帮助命令
mdbook init <directory> — 用最少的样板创建一本新书。 
mdbook build — 渲染书籍。
mdbook watch — 每当源文件发生更改时，都会重建图书。
mdbook serve — 运行一个 Web 服务器来查看这本书，并根据更改重新构建。
mdbook test — 测试 Rust 代码示例。
mdbook clean — 删除渲染的输出。
mdbook completions — 支持 shell 自动完成。 
mdbook completions --help —获取支持的 shell 列表。

mdbook build <directory> —可以将目录作为参数来用作书的root，而不是当前工作目录
mdbook build --open  — 构建后在默认浏览器打开
mdbook build --dest-dir=<directory>  —选项允许您更改输出目录 书。 相对路径是相对于书的根目录解释的
mdbook build --dest-dir=<directory> --open —更改输出目录，并在默认浏览器打开
mdbook watch <directory> — 每当源文件发生更改时，都会重建图书。

mdbook serve <directory> -p 8000 -n 127.0.0.1   —指定主机名和端口运行

## clean 命令用于删除生成的书和任何其他构建 文物。 
mdbook clean
## clean 可以将目录作为参数来用作书的 root 而不是当前工作目录。 
mdbook clean <directory>

mdbook clean --dest-dir=<directory>

mdbook test 相关：

禁用代码块上的测试

rustdoc 不测试包含 ignore属性：

image-20220718150615293

rustdoc 也不会测试指定 Rust 以外的语言的代码块：

image-20220718150638707

rustdoc 会 测试没有指定语言的代码块：

image-20220718151118246

指定目录

test可以将目录作为参数以用作书的根目录 而不是当前的工作目录。

1
2
3
4
mdbook test <directory>
## library-path (-L)选项允许您向rustdoc在构建和测试示例时使用的库搜索路径添加目录。可以用多个选项(-L foo -L bar)或用逗号分隔的列表(-L foo,bar)指定多个目录。该路径应该指向包含项目构建输出的Cargo构建## 缓存deps目录。例如，如果你的Rust项目的书在my-book目录下，那么在运行test时，下面的命令将包含板条箱的依赖项:
mdbook test <directory> -L target/debug/deps/
mdbook test <directory> --library-path target/debug/deps/

常规配置

下面是 book.toml 文件的示例： 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[book]
title = "书名"
author = ["作者1","作者2"]
description = "书的描述"
## md源文件所在root目录下的文件夹
src= "my-src"  
## 如果为en,不支持中文搜索
language= "zh"



[rust]
## 默认情况下用于代码片段的 Rust 版本。 默认 是“2015”。 单独的代码块可以用 
edition = "2021"

[build]
## 构建输出的目录
build-dir = "my-example-book"
## 是否创建缺少的页面
create-missing = false
## 使用默认的预处理器
use-default-preprocessors= false

[preprocessor.index]

[preprocessor.links]

[output.html]
additional-css = ["custom.css"]

[output.html.search]
limit-results = 15