PlantUML 扩展，用于 Python-Markdown

• 简介
• 安装
  • 使用本地PlantUML二进制文件
  • 使用远程服务器
    • 使用PlantUML服务器
    • 使用Kroki服务器
    • 文件包含管理
• 插件选项
  • 关于priority配置的说明
• 运行测试
• 使用Docker运行测试

简介

此插件实现了一个块扩展，可以用来指定一个将被转换为图像并插入到文档中的PlantUML图。

语法

::uml:: [format="png|svg|txt"] [classes="class1 class2 ..."] [alt="text for alt"] [title="Text for title"] [width="300px"] [height="300px"]
  PlantUML script diagram
::end-uml::

示例

::uml:: format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram" width="300px" height="300px"
  Goofy ->  MickeyMouse: calls
  Goofy <-- MickeyMouse: responds
::end-uml::

GitLab/GitHub块语法也被识别。示例

```plantuml id="myDiag" format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram" width="300px" height="300px"
  Goofy ->  MickeyMouse: calls
  Goofy <-- MickeyMouse: responds
```

选项是可选的（否则它们就不是选项了），但如果存在，必须按照id、format、classes、alt、title、width、height和source的顺序指定。选项值可以放在单引号或双引号内。

format参数支持以下值

• png：嵌入png图像的HTML img标签
• svg：嵌入svg图像的HTML img标签（链接不可导航）
• svg_object：嵌入svg图像的HTML object标签（链接可导航）
• svg_inline：带有内联svg图像源的HTML5 svg 标签（链接可导航，可以使用CSS规则进行操作）。
• txt：纯文本图。

width 和 height 选项必须包含一个 CSS 单位。

source 参数用于包含外部源图而不是内联代码。以下是一个使用GitLab/GitHub块语法的示例。

basic.puml

@startuml
title Authentication Sequence
    Alice->Bob: Authentication Request
    note right of Bob: Bob thinks about it
    Bob->Alice: Authentication Response
@enduml

index.md

```plantuml source="basic.puml"
'' This code is appended to the contents of basic.puml
Goofy ->  MickeyMouse: calls
Goofy <-- MickeyMouse: responds
```

安装

要使用插件与 Python-Markdown，您有以下选项。请注意，在使用此包之前，您需要配置要使用的 PlantUML 二进制文件：本地二进制文件或远程服务器（详细信息见下文）。

1. [Linux] 使用Python的 pip 包管理器并运行以下命令。运行后，包应准备就绪可供使用。

   $ pip install plantuml-markdown
   

2. [Windows] 您可以使用Windows的包管理器 Chocolatey。在提升的终端中运行以下命令

   >>> choco install plantuml
   

   (注意：此命令将安装所有依赖项，包括Java和Graphviz，有关详细信息，请参阅 https://chocolatey.org/packages/plantuml )

安装包后，您可以通过在 markdown_py 命令中激活它来使用此插件。例如

$ markdown_py -x plantuml_markdown mydoc.md > out.html

使用本地PlantUML二进制文件

您需要安装 PlantUML（请参阅网站以获取详细信息）和 Graphviz 2.26.3或更高版本。插件期望在类路径中有一个名为 plantuml 的程序。如果包管理器未安装，您可以在类路径中创建一个shell脚本。例如，将以下内容保存到 /usr/local/bin/plantuml（假设 PlantUML 已安装到 /opt/plantuml）

#!/bin/bash
java $PLANTUML_JAVAOPTS -jar /opt/plantuml/plantuml.jar ${@}

可以使用 PLANTUML_JAVAOPTS 变量来设置特定的Java选项，例如内存调整选项，或者设置PlantUML使用的系统变量，例如包括搜索路径。这可以避免修改 plantuml 脚本。例如，对于类似下面的图表

```plantuml
!include myDefs.puml

A --> B
```

您可以这样做

export PLANTUML_JAVAOPTS="-Dplantuml.include.path=$HOME/plantuml_defs"
markdown_py -x plantuml_markdown mydoc.md > out.html

可以使用环境变量 _JAVA_OPTIONS 做同样的事情，该变量默认由 java 可执行文件读取。

在Windows上，可以使用以下 plantuml.bat（感谢 henn1001）

@echo off
set mypath=%~dp0

setlocal
set GRAPHVIZ_DOT=%mypath%\Graphviz\bin\dot.exe

java %PLANTUML_JAVAOPTS% -jar %mypath%\plantuml.jar %*

确保 plantuml.bat 在路径中。

重要提示：脚本 plantuml（或Windows上的 plantuml.bat）的整个输出将被捕获并保存为图像，因此请确保脚本没有执行其他输出，即使是空白行。例如，plantuml.bat 脚本的第一行 必须 是 @echo off。

对于 Gentoo Linux，有一个在 http://gpo.zugaina.org/dev-util/plantuml/RDep 的 ebuild：您可以下载 ebuild 和 files 子文件夹，或者您可以使用 layman 添加 zugaina 存储库（推荐）。

使用远程服务器

使用PlantUML服务器

从版本 2.0 开始，可以使用 PlantUML 服务器 来渲染图表。这大大加快了图表的渲染速度，但需要将图表源发送到服务器。

您可以下载 war 并将其部署在servlet容器中，或者您可以将它作为 docker容器 运行。

在任一情况下，您都需要在配置文件中指定服务器的URL，例如

plantuml_markdown:
  server: http://www.plantuml.com/plantuml  # PlantUML server, for remote rendering
  # other global options
  insecure: False                           # set to True if the server uses self-signed certificates
  cachedir: /tmp                            # set a non-empty value to enable caching
  base_dir: .                               # where to search for diagrams to include (can be a list)
  config:                                   # PlantUML config file, relative to base_dir (a PlantUML file included in every diagram)
  format: png                               # default diagram image format
  classes: class1,class2                    # default diagram classes
  encoding: utf-8                           # character encoding for external files (default utf-8)
  title: UML diagram                        # default title (tooltip) for diagram images
  alt: UML diagram image                    # default `alt` attribute for diagram images
  image_maps: True                          # generate image maps when the format is png and there are hyperlinks
  priority: 30                              # plugin priority; the higher, the sooner will be applied (default 30)
  http_method: GET                          # GET or POST  - note that plantuml.com only supports GET (default GET)       
  fallback_to_get: True                     # When using POST, should GET be used as fallback (POST will fail if @startuml/@enduml tags not used) (default True)
  theme: bluegray                           # theme to be set, can be overridden inside puml files, (default none)
  puml_notheme_cmdlist: [                             
                          'version', 
                          'listfonts', 
                          'stdlib', 
                          'license'
                        ]                   # theme will not be set if listed commands present (default as listed)

然后您需要在命令行上指定配置文件

markdown_py -x plantuml_markdown -c myconfig.yml mydoc.md > out.html

使用Kroki服务器

从版本 3.7.0 开始，可以使用 Kroki 服务器作为 PlantUML 服务器 的替代方案。配置类似，只需使用 kroki_server 配置属性而不是 server 属性。

文件包含管理

通常，出于安全原因，远程服务器不允许执行任意 '!include' 指令。

为了绕过这个限制，插件的行为如下

• 包含 stdlib 库被认为是安全的，并由服务器管理；例如 !include <C4/C4_Container>
• 如果要包含的源以 http 或 https 开头，服务器可以处理包含；注意服务器可能会拒绝包含它们（例如 Kroki）
• 如果源名称与 server_include_whitelist 配置中的正则表达式之一匹配，则假定该文件对服务器是安全的；例如，服务器 Kroki 内部有 C4 库的副本，则 !include C4/C4_Container.puml 是一个例子
• 否则，假定该文件是本地的，并在将其发送到远程服务器之前用文件的内容替换 include 语句。此行为可以通过在 server_include_whitelist 中声明适当的正则表达式或通过在行中添加注释来更改
  • 如果注释以 local 开头，则强制包含为本地；例如，!include C4/C4_Container.puml ' local file 将搜索并读取本地文件 C4/C4_Container.puml
  • 如果注释以 remote 开头，则将包含视为服务器端包含；例如，!include my_configuration.puml 'server-side include
• 包含是递归解决的，就像在本地 PlantUML 中使用一样。

如果使用本地 PlantUML 安装，包含只有在包含在当前目录中时才会工作。如果它们在其他目录中，有两种可能性

• 使用包含中的目录（例如，!include includes/my-defs.puml）
• 在插件配置中设置 base_dir 选项（例如，base_dir: includes） AND 将默认的 plantuml 命令更改为类似 plantuml_cmd: java -Dplantuml.include.path=includes -jar path/to/plantuml.jar

插件选项

插件有多个配置选项

• alt：当图像不可用时显示的文本。默认为 uml diagram
• base_dir：搜索外部图表文件的路径。默认为 .，可以是路径列表
• cachedir：图表缓存的目录。默认为 ''，不缓存
• classes：生成图像的类列表（以空格分隔）。默认为 uml
• config：PlantUML 配置文件，相对于 base_dir（在每次图表之前包含的 PlantUML 文件，参见 PlantUML 文档）。默认为 None
• encoding：外部文件的字符编码（见 source 参数）；默认编码为 utf-8。请注意，在 Windows 上文本文件可能使用 cp1252 作为默认编码，因此设置 encoding: cp1252 可能会修复字符渲染错误。
• fallback_to_get：如果 POST 失败，则回退到 GET。默认为 True
• format：要生成的图像格式（png、svg、svg_object、svg_inline 或 txt）。默认为 png（参见上面的示例部分以进一步说明 format 的值）
• remove_inline_svg_size：当 format 为 svg_inline 时，删除生成的 SVG 的 width 和 height 属性。默认为 True
• http_method：服务器 - Http 方法 GET 或 POST。“默认为 GET
• image_maps：如果格式为 png 且图表有超链接，则生成图像映射；true、on、yes 或 1 激活图像映射，其他所有内容都禁用它。默认为 True
• insecure：如果 True，则不验证 PlantUML 服务器的 SSL 证书；当使用具有自签名证书的自定义 PlantUML 安装时设置为 True。默认为 False
• kroki_server：Kroki 服务器 URL，作为远程渲染的替代选项（图像映射必须手动禁用）。默认为 ''，如果已定义则使用 PlantUML 服务器。
• plantuml_cmd：用于本地执行 PlantUML 的命令；例如，如果您需要设置包含目录，值可以是 java -Dplantuml.include.path=includes -jar plantuml.jar。默认为 plantuml（系统脚本）。
• priority：扩展优先级。值越大表示扩展的应用时间越早于其他扩展。默认为 30。
• puml_notheme_cmdlist：如果列出命令，则不会设置主题。默认列表为 ['version', 'listfonts', 'stdlib', 'license']。**如果您要修改，请复制提供的默认列表并追加**。
• server：PlantUML 服务器 URL，用于远程渲染。默认为 ''，使用本地命令。
• server_include_whitelist：定义服务器支持的包含文件的正则表达式列表。默认为 [r'^c4.*$']（所有以 c4 开头的文件）。**有关详细信息，请参阅包含管理**。
• theme：默认主题，将被 !theme 指令覆盖。默认为空白，即 Plantuml 的 none 主题。
• title：图例的提示。

有关向 plantuml_plugin 传递选项的说明，请参阅您所使用工具的文档。

对于 markdown_py，只需编写一个配置的 YAML 文件，并在命令行上使用 -c 选项。请参阅使用 PlantUML 服务器部分中的示例。

关于priority配置的说明

使用 markdownm_py 插件时，如果它们操作相同的文本块，则可能会发生冲突。例如，是代码块或片段扩展。

每个插件都有一个配置的优先级，大多数希望作为链中的第一个或最后一个插件运行。plantuml_markdown 插件位于中间，试图在不与其他插件冲突的情况下尽可能好地工作。

如果您与其他插件一起使用时出现奇怪的行为，您可以使用 priority 配置尝试避免冲突，让插件在其他插件之前（较高值）或之后（较低值）运行。

以下是一个可能的冲突示例：问题#38。

运行测试

plantuml-markdown 已在 Python >= 3.6 和 Markdown >= 3.0.1 上进行测试。较老的 Python 或 Markdown 版本可能也能工作，但如果它们不能工作，我无法保证修复，因为它们是已结束生命周期的版本。

测试执行需要 PlantUML 的特定版本（不同版本的 PlantUML 生成的图像可能不同）。

在运行测试之前，请安装所需的依赖项。

pip install -r test-requirements.txt

要运行测试，请执行以下命令：

nose2 --verbose -F

此命令使用自定义版本的 plantuml 命令，该命令将在测试执行时下载所需的 PlantUML 版本，而不会影响系统。

使用Docker运行测试

这需要安装 docker 和 docker-compose。

首先设置一个包含所有依赖项的 Python alpine 镜像。

docker-compose build

然后运行容器以自动触发测试并打印将工作区内容映射的输出。

docker-compose up

要设置 Markdown 或 Python 的特定版本：

PTYHON_VER=3.9 MARKDOWN_VER=3.3.7 docker-compose build && docker-compose up