mdbook-admonish

基于 mdbook 的预处理程序，用于添加 Material Design 提示，基于 mkdocs-material 实现。

它将这个

```admonish info
A beautifully styled message.
```

转换为这个

示例

阅读文档 此处，以查看实际示例。您可以在 ./book 子目录中查看源代码。

使用 mdbook-admonish 的项目包括

• Rhai 书籍 (源代码)
• Trunk 指南 (源代码)
• PRQL 语言书籍 (源代码)

用法

使用任何 围栏代码块，就像您通常做的那样，但用 admonish <admonition type> 标记它

```admonish example
My example is the best!
```

请参阅 参考页面，查看支持的提示列表。您将找到

• 信息
• 警告
• 危险
• 示例

还有更多！

您还可以完全省略提示类型，在这种情况下，它将默认为 note

```admonish
A plain note.
```

附加选项

请参阅 mdbook-admonish 书籍 以获取附加选项，例如

• 自定义标题
• 自定义样式
• 可折叠块

安装

安装工具

cargo install mdbook-admonish

# If you get compilation/installation errors, try a locked installation
cargo install mdbook-admonish --locked

然后让 mdbook-admonish 添加所需的文件和配置

# Note: this may need to be rerun for new minor versions of mdbook-admonish
# see the 'Semantic Versioning' section below for details.
mdbook-admonish install path/to/your/book

# optionally, specify a directory where CSS files live, relative to the book root
mdbook-admonish install --css-dir ./assets/css .

这将添加以下配置到您的 book.toml 中。

[preprocessor.admonish]
command = "mdbook-admonish"

[output.html]
additional-css = ["./mdbook-admonish.css"]

并将文件 mdbook-admonish.css 复制到您的书籍目录中。

然后，按常规构建您的书籍。

mdbook path/to/book

可重复构建

对于适合用于CI或脚本的可重复构建，请

• 固定到特定版本
• 使用锁文件依赖项安装
• 始终安装最新的CSS资产

cargo install mdbook-admonish --vers "1.5.0" --locked
mdbook-admonish install path/to/your/book

最低支持的Rust版本（MSRV）在 Cargo.toml 中记录，并在 CHANGELOG.md 中注明。我们旨在支持大约六个月的稳定Rust。

更新

请注意，当您更新 mdbook-admonish 的版本时，除非您重新运行 mdbook-admonish install 以更新书籍中的附加CSS文件，否则不会应用更新后的样式。

如果您需要安装比已安装的版本更新的资产，mdbook 将会构建失败。

2022-04-26 12:27:52 [INFO] (mdbook::book): Book building has started
ERROR:
  Incompatible assets installed: required mdbook-admonish assets version '^2.0.0', but found '1.0.0'.
  Please run `mdbook-admonish install` to update installed assets.
2022-04-26 12:27:52 [ERROR] (mdbook::utils): Error: The "admonish" preprocessor exited unsuccessfully with exit status: 1 status

如果您想在不受破坏的情况下更新到较小的版本，您应该始终运行 mdbook-admonish install。

包含文件的处理

您可以通过设置 after 选项 来确保使用 {{#include}} 内联的内容也会被处理

[preprocessor.admonish]
after = ["links"]

这将展开 include 指令，在展开 admonish 块之前。

语义版本控制

提供以下保证：

• 主版本：包含对用户面对的markdown API或crates自身公共API的重大更改。
• 次版本：功能发布。可能包含需要重新运行 mdbook-admonish install 的CSS/HTML生成的更改。
  • 注意：在不运行 mdbook-admonish install 重新安装资产的情况下更新到次版本可能会破坏您的构建。
  • 这是由于 mdbook 预处理器架构的限制造成的。可能有助于缓解此问题的相关问题
    • https://github.com/rust-lang/mdBook/issues/1222
    • https://github.com/rust-lang/mdBook/issues/1687
    • https://github.com/rust-lang/mdBook/issues/1689
• 补丁版本：仅包含错误修复。

开发

有关开发的指南，请参阅 CONTRIBUTING.md。

感谢

此实用程序大量借鉴并受到其他项目的启发，特别是

• mdbook-mermaid
• mkdocs-material
• material-design-icons

这些项目的许可协议包含在 licences 文件夹中。