Lib.rs

CLI 辅助工具，用于管理 Markdown 文件中 PlantUML 图形源及其预览

⚡ 快速 | 💪 强大的文件选择 | ✅ CI 检查模式 | 🎨 可定制输出 | 🪝 适合 git hooks

动机

PlantUML 是管理软件规范图的一个很好的工具。除非你在 GitLab 上，GitLab 有 内置支持 解析 PlantUML 图形源，否则你需要获得 一些复杂且不方便的方法，特别是对于私有仓库。

Plantaznik 是一个你可以集成到你的工作流程中的工具，它会为你做繁琐的工作：找到引用的 PlantUML 源，生成链接并在 Markdown 文档中更新。

安装

$ cargo install plantaznik

或者从 发行版 下载预编译版本。

入门指南

在你的 Markdown 文件中，在注释中包含以下声明

<!-- plantaznik:./path/to/plantuml/source.plantuml -->
(this line will be replaced)

声明包括到源文件的路径，该路径相对于当前文件。

$ plantaznik README.md

所有目标输入文件（假设为 utf8 编码的 markdown 文件，以 \n 换行符结束）都将被处理，声明之后的行将被替换为指向官方 PlantUML 服务器的 Markdown 语法图像，链接中包含编码的源代码。

详细输出示例

$ plantaznik README.md -vvv
[DEBUG] Replacement README.md:4
[DEBUG] - ![]()
[DEBUG] + ![](https://www.plantuml.com/plantuml/svg/SyfFKj2rKt3CoKnELR1Io4ZDoSa70000)
[DEBUG] Replacement README.md:42 (no change)
[ERROR] Replacement README.md:93: Error accessing file: Read ./missing-diagram.plantuml (caused by: No such file or directory (os error 2))
[INFO ] File README.md processed (2/3 successful replacements)

用法

CLI helper for managing PlantUML diagram sources and their previews in Markdown files

Usage: plantaznik [OPTIONS] <GLOB>

Arguments:
  <GLOB>  README files glob pattern to process

Options:
  -d, --dry-run     Dry run (skips file writes)
  -c, --check-only  Check (skips file writes and error if updates would take place)
  -v, --verbose...  More output per occurrence
  -q, --quiet...    Less output per occurrence
  -h, --help        Print help
  -V, --version     Print version

高级用法

• 使用通配符选择更多文件 $ plantaznik '**/*.md'。链接将相对于当前 markdown 文件解析。
• 通过重复使用 v 开关 $ plantaznik README.md -vvvv 来增加详细程度。错误（默认）、警告、信息、跟踪。使用 -q 来静音输出
• 使用 --help 来查看使用方法和选项

保留模式

对默认生成的链接不满意？运行一次并修改生成的行以符合您的喜好。

如果替换行已经包含 PlantUML 链接（duck-regex-typed），则只替换编码后的源代码。利用此功能自定义图片 URL 位置、alt 文本或切换到 PNG 格式。给定的行不得包含指向其他图表的链接。

首次运行时，将生成以下代码：![](https://www.plantuml.com/plantuml/svg/ENCODED_SOURCE)，以下是一些如何更改行以保持代码同步的示例

• ![](https://www.plantuml.com/plantuml/png/ENCODED_SOURCE) - 将图片更改为 PNG
• ![Diagram](https://www.plantuml.com/plantuml/svg/ENCODED_SOURCE) - 添加 alt 文本
• ![](https://mycustomserver.com/plantuml/svg/ENCODED_SOURCE) - 更改服务器
• <div><img src="https://www.plantuml.com/plantuml/png/ENCODED_SOURCE"></div> - 使用自定义标记
• [![](https://www.plantuml.com/plantuml/svg/ENCODED_SOURCE)](https://www.plantuml.com/plantuml/uml/ENCODED_SOURCE) - 添加到公共服务器上编辑的超链接（使用链接两次）

注意事项

• Markdown 代码块中的声明将自动跳过

路线图

目前，我对功能和功能很满意，如果您想看到其他内容，请随时提出问题！

替代方案

• puml-for-markdown - 许多功能，包括 URL 缩短。 由于某些原因，我运行它时遇到了麻烦。在我看来，plantaznik 的优势在于速度、简单性、更好的文件过滤（glob 支持）和相对路径处理（不总是指向根目录，而是相对于文件）。
• GitHub 公开仓库的解决方案
• GitLab 支持
• GitHub 上的 Mermaid