Argdown Diagrams Preprocessor for Foliant¶
Argdown is a modeling language for creating argument maps. This preprocessor takes Argdown diagram definitions in source markdown files and converts them into images on the fly during project build.
$ pip install foliantcontrib.argdown
You will also need to install Argdown CLI and the Image Export package:
$ npm install -g @argdown/cli $ npm install -g @argdown/image-export
To enable the preprocessor, add
preprocessors section in the project config:
preprocessors: - argdown
The preprocessor has a number of options:
preprocessors: - argdown: cache_dir: !path .diagramscache/argdown converter_path: argdown format: png as_image: true params: no-title: true fix_svg_size: false
- Path to the cache directory for the generated diagrams. It can be a path relative to the project root or a global one.
To save time during build, only new and modified diagrams are rendered. The generated images are cached and reused in future builds.
- Path to Argdown CLI. By default, it is assumed that you have the
argdowncommand in your
PATH, but if it is not the case you can define it here. Default:
- Output format of the diagram image. Available formats at the time of writing:
true— inserts the diagram into the document as Markdown-image. If
false— inserts the source code of the diagram directly into the document (works only for
- Params passed to the Argdown CLI map tool. Value of this option must be a YAML-mapping. Params which require values should be specified as
param: value; params which don't require values should be specified as
To see the full list of available params, run
argdown map --help.
- Works only with
as_image: false. By default svg is embedded with hardcoded width and height so they may exceed the boundaries of your HTML page. If this option is set to
truethe svg width and height will be set to
100%which will make it fit inside your content container. Default:
To insert a diagram definition in your Markdown source, enclose it between
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>
You can override preprocessor parameters in the tag options. For example if the format for diagrams is set to
png in foliant.yml and you need one of your diagrams to render in svg, override the
format option in the tag:
SVG diagram: <argdown format="svg"> ... </argdown>
Tags also have an exclusive option
caption — the markdown caption of the diagram image.
Diagram with a caption: <argdown caption="Diagram of the opposing arguments"> ... </argdown>