Foliant 的 Argdown 图预处理器

Argdown是用于创建参数映射的建模语言。该预处理器转换源 Markdown 文件中的 Argdown 图定义，并在项目构建期间将它们动态转换为图像。

该预处理器使用Christian Voigt的Argdown Image Export 包工具将图表转换为图像。

安装

$ pip install foliantcontrib.argdown

您还需要安装 Argdown CLI 和 Image Export 包：

$ npm install -g @argdown/cli
$ npm install -g @argdown/image-export

配置

要启用预处理器，请添加argdown到preprocessors项目配置中的部分：

preprocessors:
    - argdown

预处理器有许多选项：

preprocessors:
    - argdown:
        cache_dir: !path .diagramscache/argdown
        converter_path: argdown
        format: png
        as_image: true
        params:
            no-title: true
        `fix_svg_size`: false

cache_dir ：生成图表的缓存目录的路径。它可以是相对于项目根目录的路径，也可以是全局路径。

为了在构建过程中节省时间，仅呈现新的和修改的图表。生成的图像被缓存并在未来的构建中重复使用。

converter_path : Argdown CLI 的路径。默认情况下，假定您的 中包含该argdown命令PATH，但如果不是，您可以在此处定义它。默认：argdown

format ：图表图像的输出格式。撰写本文时可用的格式：dot, graphml, svg, pdf, png, jpg, webp. 默认：png

as_image : If true— 将图表作为 Markdown-image 插入到文档中。If false— 将图表的源代码直接插入到文档中（仅适用于svg,dot和graphml格式）。默认：true

params : 传递给 Argdown CLI 地图工具的参数。此选项的值必须是 YAML 映射。需要值的参数应指定为param: value；不需要值的参数应指定为param: true.

要查看可用参数的完整列表，请运行argdown map --help.

fix_svg_size : 仅适用于svg格式和as_image: false. 默认情况下，svg 嵌入了硬编码的宽度和高度，因此它们可能会超出 HTML 页面的边界。如果此选项设置为truesvg 宽度和高度，则将设置为100%使其适合您的内容容器。默认值：false。

用法

要在 Markdown 源中插入图表定义，请将其括在<argdown>...</argdown>标签之间：

Here’s the diagram:

<argdown>
===
title: The Core Argument of Populism
author: David Lanius
date: 27/10/2018
===


This is a recontruction of right-wing populist argumentation 
based on the electoral platform of the German party...
</argdown>

您可以覆盖标签选项中的预处理器参数。例如，如果图表的格式设置为pngfoliant.yml 并且您需要其中一个图表以 svg 呈现，请覆盖format标记中的选项：

SVG diagram:

<argdown format="svg">
...
</argdown>

标签还有一个专属选项caption——图表图像的降价标题。

Diagram with a caption:

<argdown caption="Diagram of the opposing arguments">
...
</argdown>