本文介绍如何在本地运行plantuml-server。 在本地运行plantuml-server有诸多好处，首先它提供一个web界面，可以在上面编辑并生成图示；其他其他应用（比如VSCode）可以使用这个server提供的服务，快速生成图示。

安装plantuml-server

从plantuml-server可以下载其Release，是一个war文件，比如plantuml-v1.2020.1.war。这个war文件是不能直接运行的，你缺少的是一个Web服务器。

可以使用Jetty作为plantuml-war的Web服务器，可以从repo1.maven.org下载一个jetty-runner，比如：jetty-runner-9.4.27.v20200227.jar。

下载之后，把war和jar文件放在同一个目录，就可以通过下面的命令运行plantuml-server:

java -jar jetty-runner-9.4.27.v20200227.jar plantuml-v1.2020.1.war

上面会在0.0.0.0:8080运行一个http服务。如果想修改IP地址和端口，可以这样：

java -jar jetty-runner-9.4.27.v20200227.jar --host 127.0.0.1 --port 8888 plantuml-v1.2020.1.war

如果只是在本地使用的话，建议不要在0.0.0.0启动http服务。

需要注意的是，plantuml-server对生成的图片默认大小是4096x4096像素，可以通过设置环境变量修改成其他值，比如set PLANTUML_LIMIT_SIZE=8192，参考: https://plantuml.com/faq

在VSCode中使用plantuml

首先，可以在VSCode中搜索并安装vscode-plantuml扩展。

安装之后，就可以将plantuml源代码文件（.diagram或者.wsd）转化成图片（PNG或者SVG）。

vscode-plantuml默认会调用plantuml.jar来生成图片，这样响应事件比较长，因为加载jar包需要时间。可以配置vscode-plantuml来使用上一个章节配置好的plantuml-server来大幅加快生成速度。所需要做的是打开配置，并将plantuml server选项设置成相应的地址，比如：

http://127.0.0.1:8888

vscode-plantuml还支持渲染markdown中内嵌的plantuml。不过需要注意注意，由于plantuml-server采用的是http而不是https提供服务，当VSCode提示是否允许不安全内容时，要选择允许。

如果你偏好的是asciidoc而不是plantuml，VSCode也可以做到在文档预览中渲染只要需要安装扩展asciidoctor，并且增加以下配置：

"asciidoc.preview.attributes": {
  "plantuml-server-url": "http://127.0.0.1:8888"
}

在asciidoctor页面可以找到更多相关参数。

在asciidoc中插入plantuml有几种方式。

直接插入：

[plantuml,sample-diagram,svg]
----
class Sample {
}
----

引用其他plantuml文件：

[plantuml,activity,svg,align="center"]
----
include::activity_diagram.txt[]
----

上述方式的简便语法：

plantuml::activity_diagram.txt[format=svg,align="center"]

其他参考

ASCIIDOC相关

（完）

2020-10-08更新

对于某些Diagram，比如State Diagram，需要安装Graphviz。假设使用scoop安装的是2.44版的Graphviz，安装之后需要手动执行以下dot -c，参考Important note about version。否则会提示 Error: dot generates empty file. Check you dot installation.

plantuml会自动查找Graphviz的可执行文件，可以使用以下命令测试查找的情况：

 java -jar plantuml.jar -testdot

也可以使用下面的uml源代码

@startuml
testdot
@enduml

如果找不到Graphviz的话，可能需要指定GRAPHVIZ_DOT环境变量到dot的可执行文件。

（更新完）

2020-12-17更新

VSCode的AsciiDoc插件貌似不能通过plantuml server来渲染Plantuml了。一个折衷的办法是通过Kroki来做后端跟各种作图工具进行交互。

AsciiDocFx是一款基于JavaFx的AsciiDoc写作环境，可以一试。

一些额外参考

（更新完）