foliantcontrib.plantuml 1.0.10
PlantUML diagrams preprocessor for Foliant.
License: MIT

[![](https://img.shields.io/pypi/v/foliantcontrib.plantuml.svg)](https://pypi.org/project/foliantcontrib.plantuml/) [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.plantuml.svg?label=GitHub)](https://github.com/foliant-docs/foliantcontrib.plantuml)

# PlantUML Diagrams Preprocessor for Foliant

[PlantUML](http://plantuml.com/) 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

```bash
$ pip install foliantcontrib.plantuml
```

## Config

To enable the preprocessor, add `plantuml` to `preprocessors` section in the project config:

```yaml
preprocessors:
    - plantuml
```

The preprocessor has a number of options:

```yaml
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](https://plantuml.com/command-line). Default: `png`.

> Another way to specify format is to use `t<format>` option in `params`.

`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):

```markdown
Here’s a diagram:

<plantuml>
    @startuml
        ...
    @enduml
</plantuml>
```

To set a caption, use `caption` option:

```markdown
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.

```markdown
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.