适用于Python-Markdown 的PlantUML扩展

该插件实现了一个块扩展，可用于指定将转换为图像并插入到文档中的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 format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram" width="300px" height="300px"
  Goofy ->  MickeyMouse: calls
  Goofy <-- MickeyMouse: responds
```

选项是可选的（否则不会是选项），但如果存在必须按顺序指定format、classes、alt、title、width、height和source。选项值可以用单引号或双引号括起来。

支持的format参数值为：

• png: 嵌入 png 图像的 HTMLimg标记
• svg：带有嵌入 svg 图像的 HTMLimg标记（链接不可导航）
• svg_object：带有嵌入 svg 图像的 HTMLobject标记（链接可导航）
• svg_inline: 带有内嵌 svg 图像源的 HTML5svg标签（链接是可导航的，可以使用 CSS 规则进行操作）
• txt: 纯文本图。

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

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

基本的.puml

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

索引.md

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

安装

要将插件与Python-Markdown一起使用，您有以下选择：

• with pip, 做一个简单pip install plantuml-markdown的, 插件应该可以使用了

• 在 Windows 上，你可以使用Chocolatey，一个 Windows 的包管理器：做一个 choco install plantuml，你就可以开始工作了（这个命令将安装所有依赖项，包括 Java 和 Graphviz，详见https://chocolatey.org/packages/plantuml）

• 将文件复制到Python-Markdownplantuml-markdown.py的extensions文件夹中。例如，对于 Python 2.7，您必须执行以下操作：

  $ sudo cp plantuml-markdown.py /usr/lib/python27/site-packages/markdown/extensions/
  

• 将文件复制到您家中的某处。一个不错的选择可能是user-site路径，例如（bash语法）：

  $ export INSTALLPATH="`python -m site --user-site`/plantuml-markdown"
  $ mkdir -p "$INSTALLPATH"
  $ cp plantuml-markdown.py "$INSTALLPATH/mdx_plantuml-markdown.py"
  $ export PYTHONPATH="$INSTALLPATH"
  

  PYTHONPATH运行前必须导出markdown_py，也可以将定义放入~/.bashrc.

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

markdown_py -x plantuml_markdown mydoc.md > out.html

但在使用它之前，您需要配置使用哪个PlantUML二进制文件：本地二进制文件或远程服务器。

使用本地 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在路径上。

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

使用 PlantUML 服务器

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

您可以下载战争并部署在 servlet 容器中，也可以将其作为docker 容器运行。

无论哪种情况，您都需要在配置文件中指定服务器的 URL，例如：

plantuml_markdown:
  server: http://www.plantuml.com/plantuml  # PlantUML server, for remote rendering
  # other global options
  cachedir: /tmp                            # set a non-empty value to enable caching
  base_dir: .                               # where to search for diagrams to include
  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
  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

priority配置注意事项

markdownm_py如果插件扩展操作相同的文本块，它们可能会发生冲突。示例是Fenced Code Blocks 或Snippets。

每个插件都配置了优先级，大多数都希望作为链中的第一个或最后一个插件运行。该 plantuml_markdown插件适合中间，尽量在不与其他插件冲突的情况下发挥最佳作用。

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

作为可能的冲突的示例，请参见问题 #38。

插件选项

该插件有几个配置选项：

• alt：当图像不可用时显示的文本。默认为uml diagram
• base_dir: 搜索外部图表文件的路径
• cachedir: 用于缓存图表的目录。默认为'', 无缓存
• classes：生成图像的空格分隔的类列表。默认为uml
• encoding: 外部文件的字符编码（见source参数）；默认编码是utf-8. 请注意，在 Windows 上，文本文件可能会使用cp1252默认编码，因此设置encoding: cp1252可能会修复不正确的字符呈现。
• fallback_to_getGET:如果POST失败则回退。默认为真
• format: 要生成的图像格式（、png、svg或svg_object）。默认为（有关 值的进一步解释，请参见上面的示例部分）svg_inlinetxtpngformat
• http_method: 服务器的 Http 方法 -GET或POST. “默认为GET
• priority: 扩展优先级。较高的值意味着比其他值更快地应用扩展。默认为30
• puml_notheme_cmdlist: 如果列出的命令存在，则不会设置主题。默认列表是 ['version', 'listfonts', 'stdlib', 'license']. 如果修改，请复制提供的默认列表并附加
• server: PlantUML 服务器 url，用于远程渲染。默认为''，使用本地命令
• theme：要使用的默认主题，将被 !theme 指令覆盖。默认为空白，即 Plantumlnone主题
• title：图表的工具提示

有关将选项传递给plantuml_plugin您正在使用的工具的文档。

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

运行测试

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