mdBook webinclude 预处理器

webinclude 预处理器的工作方式类似于内置的 include 链接，该链接在书的某个部分插入（部分）本地文件。使用 webinclude 也可以实现相同的效果，但是不是指定文件路径，而是可以使用 URL。该 URL 的来源会像使用 include 一样获取和处理。

安装 & 设置

可以使用 Cargo 安装此预处理器

cargo install mdbook-webinclude

将以下行添加到您的 book.toml 文件中

[preprocessor.webinclude]

现在您可以在书中使用以下描述的 webinclude 链接。

用法

包含 Markdown

由于文本是在渲染书籍之前插入的，因此可以包含来自其他源的 Markdown。这在例如您的书籍位于与实际程序不同的存储库时特别有用。

{{#webinclude https://example.org/document.md}}

包含文本

也可以直接插入文本，除非在代码块中使用，否则这种方法不太实用。例如，您可以包含来自不同存储库的源代码，并将其包裹在适当的代码块中。

```
{{#webinclude https://example.org/main.rs}}
```

包含文件的部分

通常您只需要文件的一部分，例如示例中的相关行。支持四种不同的模式进行部分包含。

{{#webinclude https://example.org/document.md 2}}
{{#webinclude https://example.org/document.md :10}}
{{#webinclude https://example.org/document.md 2:}}
{{#webinclude https://example.org/document.md 2:10}}

第一个命令仅包含文件的第二行。第二个命令包含到第 10 行的所有行，即从第 11 行到文件末尾的行被省略。第三个命令包含从第 2 行开始的所有行，即省略第一行。最后一个命令包含 document.md 的摘录，包括第 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
{{#webinclude file.rs:component}}
```

Here is a system:
```rust,no_run,noplayground
{{#webinclude file.rs:system}}
```

This is the full file.
```rust,no_run,noplayground
{{#webinclude file.rs:all}}
```

转义

对于非常罕见的情况，您想要字面地包含 {{#webinclude ...}} 简单地在其前加上反斜杠 (\)。

设置 HTTP 头部

HTTP 头部可以在 book.toml 文件中配置。

更改您的 book.toml 文件中的这一行

- [preprocessor.webinclude]
+ [preprocessor.webinclude.headers]

然后您可以按以下方式设置头部。

[preprocessor.webinclude.headers]
user-agent = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:50.0) Gecko/20100101 Firefox/50.0"
accept = "text/plain"