Asciidoctor Diagram 是一组 Asciidoctor 扩展，它可以让你向 AsciiDoc 文档中添加图表，而这些图表则是使用纯文本描述的。
扩展支持 BlockDiag （BlockDiag、SeqDiag、ActDiag、NwDiag）， Ditaa、GraphViz、Mermaid、PlantUML、Shaape 和 WaveDrom 语法。
每个扩展都是运行图表处理器，然后根据输入文本来生成一个 SVG、PNG 或 TXT 文件。 生成的文件随后插入到你处理过的文档中。
Asciidoctor Diagram 是受 AsciiDoc PlantUML filter 启发而产生的项目。
该文档有如下语言的翻译版：
|
Tip
|
本文档是 README 的翻译版。如果发现有什么不一致或者错误的地方，请以原文档为准。 |
Asciidoctor Diagram 是一个 RubyGem ，它可以使用 gem 或 bundle 命令来安装。
你可以通过在命令行中输入 gem install 来安装 Asciidoctor Diagram。
$ gem install asciidoctor-diagram
或者，先在项目的 Gemfile 文件中添加如下内容：
gem 'asciidoctor-diagram', '~> 1.4.0'然后在命令中执行 bundle 命令。
$ bundle
一个图表可以直接书写在文档内部的文本块中，这个文本块还可以接受几个属性。
[diagram-type, generated-file-name, generated-image-format] // (1) (2) (3)
.... // (4)
符合相应语法的图表
....-
属性列表中第一个位置的属性指明所使用的图表类型。
-
第二个位置的属性指明生成文件的文件名。如果没有指明，则默认使用原文件名来命名新生成的文件名。
-
第三个位置的属性指明生成图表的格式，类似三个字符的文件扩展名。
-
将属性列表直接放在文本块分隔符（ .... ）上面。你也可以使用开放块（
--）作为另一个选择。
图表类型以及可用的输出格式如下：
| 图表类型 | gif | png | svg | txt |
|---|---|---|---|---|
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
||||
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
☑️ |
☑️ |
||
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
☑️ |
|||
☑️ |
☑️ |
下面的例子演示一个直接书写在 AsciiDoc 文档中的基本 ditaa 块的结构。
[ditaa]
....
+-------------+
| Asciidoctor |-------+
| diagram | |
+-------------+ | PNG out
^ |
| ditaa in |
| v
+--------+ +--------+----+ /---------------\
| | --+ Asciidoctor +--> | |
| Text | +-------------+ | Beautiful |
|Document| | !magic! | | Output |
| {d}| | | | |
+---+----+ +-------------+ \---------------/
: ^
| Lots of work |
+-----------------------------------+
....上面的 ditaa 块生成的图表如下图所示：
上面渲染后的图表得到的文件名为 58372f7d2ceffae9e91fd0a7cbb080b6.png。
这串长数字是源码的校验和，由 asciidoctor-diagram 计算所得。
如果想给所生成的文件一个更具有意义的名字，请在 target 属性中填写。
这可以很容易通过指明第二个位置的属性或者一个命名属性来指明文件名。
下面的两个例子将生成文件名为 ditaa-diagram.png 的文件。
[ditaa, "ditaa-diagram"] ---- <snip> ---- [ditaa, target="ditaa-diagram"] ---- <snip> ----
下面的例子演示一个直接书写在 AsciiDoc 文档中的基本 PlantUML 块的结构。
[plantuml, diagram-classes, png] // (1) (2) (3)
....
class BlockProcessor
class DiagramBlock
class DitaaBlock
class PlantUmlBlock
BlockProcessor <|-- DiagramBlock
DiagramBlock <|-- DitaaBlock
DiagramBlock <|-- PlantUmlBlock
....-
这个图表是使用 PlantUML 书写的，所以第一个位置的属性应该被指明为
plantuml图表类型。 -
生成的图表文件的名字被书写在第二个位置的属性。
-
生成的文件格式放置在第三个属性位置。
你可以使用 -r 标识在终端中加载 Asciidoctor Diagram。
$ asciidoctor -r asciidoctor-diagram sample.adoc
你也可以在其他的转化器中使用 Asciidoctor Diagram，例如 Asciidoctor EPUB。
Asciidoctor-epub3 也是通过 -r 标识来加载。
$ asciidoctor -r asciidoctor-diagram -r asciidoctor-epub3 -b epub3 sample.adoc
或者，你也可以通过 asciidoctor-epub3 命令来调用 Asciidoctor 和 EPUB 转化器。
这个命令隐式地设置 -r 和 -b 标识用于 EPUB3 输出。
$ asciidoctor-epub3 -r asciidoctor-diagram sample.adoc
在你的程序中，你可以加载并注册整个图表扩展集合。
require 'asciidoctor-diagram'或者，加载并注册每一个单独的扩展。
require 'asciidoctor-diagram/<extension_name>'<extension_name> 可以是 blockdiag、ditaa、erd、graphviz、meme、mermaid、plantuml、shaape 或 wavedrom。
加载一个或多个这些文件将为所有需要处理的文档自动注册这些扩展。
如果你需要更细粒度控制扩展的可用性， 则可以使用 asciidoctor-diagram/<extension_name>/extension。
它将加载扩展但是不会向 Asciidoctor 扩展注册表中注册。
你可以在恰当的时机使用 Asciidoctor::Extensions API 来手动注册扩展。
本文档使用 ditaa 图表作为示例，演示了 asciidoctor-diagram 块的一系列特性。
图表扩展还可以以块宏的形式来使用。
宏名::原文件名[生成的文件扩展名] // (1) (2) (3)-
宏名和以块形式的块名相同。
-
原文件名指明包含图表源代码的外部文件。
-
第一个可选的属性指明用于生成图表的文件扩展名（也就是
format）
源文件的名字是相对正在处理的文件的位置的相对路径。
当 Asciidoctor Diagram 将图片写入磁盘时，它将根据如下选项依次来决定将文件写入到何处。
-
{imagesoutdir}如果imagesoutdir属性被指明 -
{outdir}/{imagesdir}如果outdir属性被指明 -
{to_dir}/{imagesdir}如果to_dir属性被指明 -
{base_dir}/{imagesdir}
Asciidoctor Diagram 依赖外部工具来生成图片。
大多数情况下，它会自动从 PATH 环境变量指定的每一个路径中查找定位有特定可执行的工具。
如果你安装的工具不在 PATH 指明的路径中，你可以通过手动指明相关属性来覆盖工具的定位位置。
下面的表格指明每一个图表类型必须依赖的工具，工具被安装的位置和用于覆盖默认位置的文档属性。
| Diagram Type | Tool | Attribute |
|---|---|---|
actdiag |
|
|
blockdiag |
|
|
ditaa |
|
|
erd |
|
|
graphviz |
|
|
meme |
|
|
mermaid |
|
|
nwdiag |
|
|
packetdiag |
|
|
plantuml |
|
|
rackdiag |
|
|
seqdiag |
|
|
shaape |
|
|
wavedrom |
|
|
|
举例说明一下，假如你将 actdiag 安装在 /home/me/actdiag/bin 下，这路径不在 PATH 范围内，则你可以在命令行中指明它的位置：
$ asciidoctor -a actdiag=/home/me/actdiag/bin/actdiag -r asciidoctor-diagram sample.adoc
meme 扩展提供了一个基本的 ‘Advice Animal’ 风格的图片生成器。 使用一个例子就能非常方便地解释它的用法。
meme::yunoguy.jpg[Doc writers,Y U NO \\ AsciiDoc]宏块的目的是告诉扩展使用哪些图像作为背景。
头两个位置的属性是 top 和 bottom，用于标题的顶部和底部。
出现在 \\ 周围的空白符将被解释为换行符。
块宏海支持如下的命名熟悉：
-
fillColor：文字的填充颜色。默认为white。 -
strokeColor：文本的轮廓颜色。默认为black。 -
strokeWidth：文本轮廓的宽度。默认为2。 -
font: 文本的字体外观。默认为Impact。 -
options：逗号分隔的标识列表，用于修改图片的渲染。目前只支持noupcase， 它可以禁用大写的标签。 -
target（第三位可选参数）：生成文件的文件名。如果没有指定，则将会使用自动生成的文件名。 -
format（第四位可选参数）：生成图片的格式。meme 扩展支持png和gif。、