mdBook PlantUML

将 PlantUML 代码块渲染为书中的图像的 mdBook 预处理器。

内容

• 使用方法
• 配置选项
• 服务器配置
• 渲染问题的故障排除
• 变更日志
• 在 Linux 上构建/安装

使用方法

首先在 book.toml 文件中创建预处理器

[book]
authors = ["Dzjengis Khan"]
multilingual = false
src = "src"
title = "mdBook PlantUML preprocessor"

[preprocessor.plantuml]
plantuml-cmd="plantuml.exe"

以上假设 mdbook-preprocessor 和 plantuml 可执行文件都在您的路径中。

然后在您的书文本中添加一个 PlantUML 代码块

Some text here

```plantuml
@startuml
A --|> B
@enduml
```

Some more text.

如果可能，plantuml 代码块将被替换为 SVG 图像的引用，否则如果是 PlantUML 不支持 svg 的请求图类型（例如 ditaa），则替换为 png。

图像格式

默认情况下，图像为 svg 或 png，具体取决于图类型。如果需要，它可以更改为 PlantUML 的其他输出格式（注意，某些格式可能不被所有浏览器或 PlantUML 服务器实现所支持）。

请参阅 https://plantuml.com/command-line（输出文件类型）以获取可用格式。mdbook-plantuml 使用短参数名（区分大小写，不带 '-'）

A diagram in UTF-8 text format (inlined automatically)
```plantuml,format=utxt
@startuml
A --|> B
@enduml
```

Force png format:
```plantuml,format=png
@startuml
A --|> B
@enduml
```

选项

• plantuml-cmd: 为 PlantUML 选择的可选命令覆盖（在 Windows 上默认为 "java -jar plantuml.jar"，在 Linux 上为 "/usr/bin/plantuml"）。当提供 URL 时，假定您想使用 PlantUML 服务器实现来生成图像。
• clickable-img: 可选（默认为 false）。当设置为 true 时，图像可以点击并在新标签页/窗口中打开。
• use-data-uris: 可选（默认为 false）。当设置为 true 时，图像作为内联 Data URIs 渲染（不需要外部文件）。

功能

• plantuml-server 仅添加 http 服务器支持
• plantuml-ssl-server 添加 https 服务器支持（默认）

示例：不安装服务器支持：cargo install mdbook-plantuml --no-default-features

安装支持HTTP服务：cargo install mdbook-plantuml --no-default-features --features plantuml-server

安装支持HTTPS服务：cargo install mdbook-plantuml --no-default-features --features plantuml-ssl-server

示例数据URI配置

[book]
authors = ["Chuck Norris"]
multilingual = false
src = "src"
title = "mdBook PlantUML preprocessor"

[preprocessor.plantuml]
plantuml-cmd="plantuml"
use-data-uris=true

示例服务器配置

以下是一个示例服务器配置。

您可以通过追加URL“/png/SoWkIImgAStDuGh8ISmh2VNrKT3LhR5J24ujAaijud98pKi1IW80”来测试您的服务器。使用下面的示例，您将得到以下URL：此URL。当它正常工作时，您应该看到以下图像

[book]
authors = ["Dzjengis Khan"]
multilingual = false
src = "src"
title = "mdBook PlantUML preprocessor"

[preprocessor.plantuml]
plantuml-cmd="https://127.0.0.1:8080/plantuml"

渲染问题的故障排除

mdBook通过stdio与预处理器通信。因此，预处理器的日志输出不会打印到屏幕上。当预处理器的Markdown错误输出不足以满足您的要求时，您可以使用命令行开关-l将日志重定向到文件./output.log。请参阅下面的配置示例

[book]
authors = ["Sytse Reitsma"]
multilingual = false
src = "src"
title = "mdBook E2E test book"

[preprocessor.plantuml]
plantuml-cmd="https://127.0.0.1:8080/plantuml"
command = "mdbook-plantuml -l"

变更日志

0.8.0 (2022-07-04)

• 非常感谢 @danieleades 进行清理和现代化
• 点击图像以在隔离环境中打开它（感谢 @YushiOMOTE）
• 添加对puml代码块的支持作为plantuml的替代方案（各种程序的本地IDE支持，感谢 @YushiOMOTE）
• 现在可以按代码块配置图表格式（例如png或svg）
• 支持数据URL，感谢 @knightflower1989）。此功能可以用来解决mdbook serve循环问题。

0.7.0 (2020-08-29)

• 🏎️ 速度！添加了缓存，只重新生成更改的代码块，而不是所有代码块。
• PlantUML服务器和ssl服务器（默认为ssl服务器）被功能门控。 问题 #16
• 修复了使用mdbook serve命令时无限重建循环的问题。由于预处理器输出无法直接写入书籍输出目录，因此不幸的是必须在src目录中创建图像（mdBook更改）。当图像更新时，您仍然需要进行一次额外的重建，我无法防止这种情况（mdBook的gitignore文件应该能够防止这种情况，但它不能）。 问题 #17

0.6.0-beta (2020-01-29)

• 🏎️ 速度！添加了缓存，只重新生成更改的代码块，而不是所有代码块。
• PlantUML服务器和ssl服务器（默认为ssl服务器）被功能门控。 问题 #16
• 放弃了pulldown-cmark，转而使用自家的markdown解析器。从markdown转换回来会导致文档发生变化。 问题 #15
• 这些是相当重大的更改，因此有了beta标签。

0.5.0 (2019-11-08)

• 从v0.3.2开始的mdBook在渲染开始时删除书籍输出目录，导致所有生成的预处理器输出也被删除。目前唯一的解决方案是将图像输出到src目录。这很丑陋，但是一个临时解决方案，直到mdBook允许以其他方式从预处理器添加资源。请参阅 这个问题
• 更详细的README.md

0.4.0 (2019-09-25)

• PlantUML服务器支持，太棒了！
• 修复了第一个PlantUML图像之后的所有Markdown不再渲染的问题（预处理器似乎无法输出HTML）。
• 嵌套章节中的图像现在有正确的URL（感谢 @rafasf）。
• 允许将日志记录到文件中，以便排查预处理器问题。

0.3.0 (2019-08-29)

• 生成SVG图像文件而不是内联SVG
• 对于ditaa图像，由于PlantUML不支持ditaa图表的svg，因此重新使用png

0.2.0 (2019-07-08)

• 生成的SVG图像现在被包裹在一个带有类'type' 'plantuml'的div中
• 当SVG生成失败时提供更详细的错误信息（包括可能的错误原因提示）。

0.1.0 (2019-07-08)

• 第一个版本

在Linux上构建和安装

我主要在Windows上工作，而且据我所知，Rust还不那么便携。

当你在Linux上安装/构建mdbook-plantuml时遇到以下错误

failed to run custom build command for `openssl-sys v0.9.49`

确保您已安装libssl-dev和pkg-config

sudo apt update
sudo apt install libssl-dev pkg-config