PlantUML diagrams preprocessor for Foliant.
Project description
PlantUML Diagrams Preprocessor for Foliant
PlantUML is a tool to generate diagrams from plain text. This preprocessor finds PlantUML diagrams definitions in the source and converts them into images on the fly during project build.
Installation
$ pip install foliantcontrib.plantuml
Config
To enable the preprocessor, add plantuml
to preprocessors
section in the project config:
preprocessors:
- plantuml
The preprocessor has a number of options:
preprocessors:
- plantuml:
cache_dir: !path .diagramscache
plantuml_path: plantuml
format: png
params:
...
parse_raw: true
as_image: true
cache_dir
: Path to the directory with the generated diagrams. It can be a path relative to the project root or a global one; you can use ~/
shortcut.
> **Note**
>
> To save time during build, only new and modified diagrams are rendered. The generated images are cached and reused in future builds.
plantuml_path
: Path to PlantUML launcher. By default, it is assumed that you have the command plantuml
in your PATH
, but if PlantUML uses another command to launch, or if the plantuml
launcher is installed in a custom place, you can define it here.
format
: Diagram format, list of supported formats. Default: png
.
Another way to specify format is to use
t<format>
option inparams
.
params
: Params passed to the image generation command:
preprocessors:
- plantuml:
params:
config: !path plantuml.cfg
To see the full list of params, run the command that launches PlantUML, with `-h` command line option.
parse_raw
: If this flag is true
, the preprocessor will also process all PlantUML diagrams which are not wrapped in <plantuml>...</plantuml>
tags. Default value is false
.
as_image
: If true
— inserts scheme into document as md-image. If false
— inserts the file generated by PlantUML directly into the document (only for svg
format). Default: true
Usage
To insert a diagram definition in your Markdown source, enclose it between <plantuml>...</plantuml>
tags (indentation inside tags is optional):
Here’s a diagram:
<plantuml>
@startuml
...
@enduml
</plantuml>
To set a caption, use caption
option:
Diagram with a caption:
<plantuml caption="Sample diagram from the official site">
@startuml
...
@enduml
</plantuml>
You can override values from the preprocessor config for each diagram.
By default, diagrams are in PNG. But this diagram is in EPS:
<plantuml caption="Vector diagram" format="eps">
@startuml
...
@enduml
</plantuml>
Sometimes it can be necessary to process auto-generated documents that contain multiple PlantUML diagrams definitions without using Foliant-specific tags syntax. Use the parse_raw
option in these cases.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for foliantcontrib.plantuml-1.0.9.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d60c91fb4c1dc74899c65db6960612fa35ff5df7214e546fc31ffd3fa17d25bf |
|
MD5 | ae14a27dca42b19f27a3e4eefecf9d2f |
|
BLAKE2b-256 | 7e40977dac01c4085405fc4072dad99697d1e16e0d7d2069b857b5cf7735a721 |
Hashes for foliantcontrib.plantuml-1.0.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | df0f44ba1d95bbe82caec0653dbdddeaaeb8572155f1e877843bab1c2762eef5 |
|
MD5 | fdd2da9f1e7538e2c6c2ff623d059752 |
|
BLAKE2b-256 | 3a567b75dc1acb34c8866a788d427a323f77fa935a965db8ed7e307cb1034243 |