Graphviz: Pelican的插件

Graphviz是一个Pelican插件，允许使用Markdown标记格式包含Graphviz图像。Graphviz图形的代码作为文章源代码中的块包含，并使用Base64格式嵌入到HTML中。

安装

此插件可以通过以下方式安装

python -m pip install pelican-graphviz

系统上必须安装Graphviz，否则此插件将被禁用。在基于Debian的系统上可以通过以下方式安装Graphviz：

sudo aptitude install graphviz

对于macOS，可以通过Homebrew安装Graphviz

brew install graphviz

使用方法

在Markdown源中，Graphviz代码必须作为一个单独的块插入（即通过空白行与其他材料分开），如下所示：

..graphviz dot
digraph G {
  graph [rankdir = LR];
  Hello -> World
}

这将像这样在您的文章中插入一张图片

块必须以..graphviz开始（这是可配置的——见下文）。第一行中的单词dot表示将运行以生成图片的程序。可用的程序有：dot、neato、twopi、circo、fdp、sfdp和patchwork（有关详细信息，请参阅Graphviz文档）。Graphviz代码必须从块的第二行开始。请注意，Graphviz块内不允许使用换行符。

使用CSS进行样式设置

图片以HTML中的<img>元素形式生成，并位于HTML元素内部（默认为<div>，但这可配置——见下文）。后者具有类graphviz（这也是可配置的——见下文）。可能的CSS样式如下：

div.graphviz  {
    margin: 10px;
}
div.graphviz img {
    display: block;
    padding: 5px;
    margin-left: auto;
    margin-right: auto;
    text-align: center;
    border-style: solid;
    border-width: 1px;
    border-color: rgb(192, 177, 177);
    -webkit-border-radius: 5px;
}

配置

以下变量可以在Pelican设置文件中设置

• GRAPHVIZ_HTML_ELEMENT：将生成的Graphviz图片插入其内的HTML（默认为'div'；另一个合理的可能性是'span'）。

• GRAPHVIZ_IMAGE_CLASS：<div>元素包括生成的Graphviz图片的类（默认为'graphviz'）。

• GRAPHVIZ_BLOCK_START：Markdown中Graphviz块的起始标签（默认为'..graphviz'）。

• GRAPHVIZ_COMPRESS：将生成的SVG XML压缩为图片（默认为True）。不压缩时，更多SVG功能可用，例如在Graphviz图中包含可点击的URL。

以下语法可以覆盖每个单独块的上面的值

..graphviz [key=val, ...] dot

允许的键是html-element、image-class和compress。对于后者，值可以是yes或no。

输出图片格式

嵌入图片的格式是SVG，目前无法更改该格式。选择此格式而不是其他格式（如PNG）有两个原因。首先，生成的Base64中的SRC字符串似乎比PNG更短。其次，图片将以高质量的矢量格式在浏览器中可用。作为警告，请注意，这种选择可能会阻止在不支持SVG的浏览器中显示。

替代方案

此插件的替代方案是Graphviz标签，由Liquid Tags插件提供，它在几个方面与此插件不同。首先，Liquid Tags版本使用语法{% graphviz { <program> […] } %}，而此Graphviz插件使用Markdown扩展语法..graphviz <program> […]。关于渲染输出，差异如下：

• 两个插件都输出一个具有class="graphviz"的元素。然而，只有Graphviz插件允许您通过配置变量（GRAPHVIZ_IMAGE_CLASS）更改类名。
• 液态标签将图像编码为 src="data:image/png;base64,[…]"，而Graphviz插件将其编码为 src="data:image/svg+xml;base64,[…]"。这有两个影响。首先，该Graphviz插件生成的HTML代码大小要小得多。例如，Graphviz代码 digraph graphname {a -> b -> c; b -> d;} 的Base64字符串大小是原来的四分之一。其次，Liquid Tags版本生成的是位图文件，而此Graphviz插件生成的是矢量图像，可以放大而不损失图像质量。
• 液态标签将Graphviz图像输出到 <span> 中，而此Graphviz插件提供了容器元素的选择。

待办事项

欢迎贡献使此插件与reStructuredText内容兼容的代码。

贡献

欢迎并非常感谢贡献。每一份努力都很有帮助。您可以通过改进文档、添加缺失的功能和修复错误来贡献。您还可以通过审查和评论现有问题来提供帮助。

要开始为此插件做出贡献，请查阅Pelican贡献文档，从贡献代码部分开始。

致谢

感谢Justin Mayer帮助将此插件迁移到Pelican插件组织下，以及感谢Maxim Kochurov引入了GRAPHVIZ_COMPRESS配置变量。

作者

版权所有 © 2015, 2021, 2023 Rafael Laboissière rafael@laboissiere.net

许可证

本项目受AGPL 3.0许可证的条款约束。