https://github.com/foliant-docs/foliantcontrib.plantuml
PlantUML diagrams preprocessor for Foliant.
https://github.com/foliant-docs/foliantcontrib.plantuml
Last synced: 5 months ago
JSON representation
PlantUML diagrams preprocessor for Foliant.
- Host: GitHub
- URL: https://github.com/foliant-docs/foliantcontrib.plantuml
- Owner: foliant-docs
- License: mit
- Created: 2018-03-03T09:26:55.000Z (over 8 years ago)
- Default Branch: develop
- Last Pushed: 2025-07-30T06:09:33.000Z (11 months ago)
- Last Synced: 2025-09-22T21:44:45.693Z (9 months ago)
- Language: Python
- Homepage:
- Size: 33.2 KB
- Stars: 0
- Watchers: 2
- Forks: 3
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.org/project/foliantcontrib.plantuml/) [](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` 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 `...` 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 `...` tags (indentation inside tags is optional):
```markdown
Here’s a diagram:
@startuml
...
@enduml
```
To set a caption, use `caption` option:
```markdown
Diagram with a caption:
@startuml
...
@enduml
```
You can override values from the preprocessor config for each diagram.
```markdown
By default, diagrams are in PNG. But this diagram is in EPS:
@startuml
...
@enduml
```
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.