search

sytsereitsma / mdbook-plantuml

mdBook preprocessor to render PlantUML diagrams to png images in the book output directory
MIT License
76 stars 14 forks source link
book documentation mdbook plantuml

readme

mdBook PlantUML

mdBook preprocessor to render PlantUML code blocks as images in your book.

Contents

Usage

First create the preprocessor in your book.toml file:

[book]
authors = ["Dzjengis Khan"]
multilingual = false
src = "src"
title = "mdBook PlantUML preprocessor"

[preprocessor.plantuml]
plantuml-cmd="plantuml.exe"

The above assumes both the mdbook-preprocessor and the plantuml executable are on your path.

Then simply add a PlantUML code block in your book text:

Some text here

```plantuml
@startuml
A --|> B
@enduml

Some more text.


The plantuml code block will be replaced an image reference to an SVG image if
possible, or png if PlantUML does not support svg for the requested diagram type
(i.e. ditaa).

## Image formats
The image is svg, or png by default, depending on the diagram type. If desired it can be changed to another one of PlantUMLs output formats (note that some formats are not supported by all browsers and or PlantUML server implementations).

See https://plantuml.com/command-line (Types of Output File) for available formats. mdbook-plantuml uses the short param name (case sensitive, without the '-')

````markdown
A diagram in UTF-8 text format (inlined automatically)
```plantuml,format=utxt
@startuml
A --|> B
@enduml

Force png format:

@startuml
A --|> B
@enduml

## Options
- **plantuml-cmd:** Optional command override for PlantUML (defaults to "java -jar plantuml.jar" on Windows and "/usr/bin/plantuml" on Linux).
  When a URL is provided it is assumed you want to generate the images using a PlantUML server implementation.
- **clickable-img:** Optional (```false``` by default). When ```true``` images can be clicked and are opened in a new tab/window.
- **use-data-uris:** Optional (```false``` by default). When ```true``` images are rendered as inline Data URIs (not requiring external files).

## Features
- **plantuml-server** Add http server support only
- **plantuml-ssl-server** Add https server support (default)

Examples:
Install without server support:
```cargo install mdbook-plantuml --no-default-features```

Install with http server support:
```cargo install mdbook-plantuml --no-default-features --features plantuml-server```

Install with https server support:
```cargo install mdbook-plantuml --no-default-features --features plantuml-ssl-server```

## Example Data URI configuration
```toml
[book]
authors = ["Chuck Norris"]
multilingual = false
src = "src"
title = "mdBook PlantUML preprocessor"

[preprocessor.plantuml]
plantuml-cmd="plantuml"
use-data-uris=true

Example server configuration

Below is an example server configuration.

You can test your server by appending the URL with "/png/SoWkIImgAStDuGh8ISmh2VNrKT3LhR5J24ujAaijud98pKi1IW80". Using the example below this example you'd end up with this URL. When it is working correctly you should see the following image:

[book]
authors = ["Dzjengis Khan"]
multilingual = false
src = "src"
title = "mdBook PlantUML preprocessor"

[preprocessor.plantuml]
plantuml-cmd="http://localhost:8080/plantuml"

Troubleshooting rendering issues

mdBook communicates to the preprocessor using stdio. As a result log output from the preprocessor is not printed to the screen. When the preprocessor's markdown error output is insufficient for you it is possible to redirect logging to the file ./output.log by using the command line switch -l. See the config below for an example:

[book]
authors = ["Sytse Reitsma"]
multilingual = false
src = "src"
title = "mdBook E2E test book"

[preprocessor.plantuml]
plantuml-cmd="http://localhost:8080/plantuml"
command = "mdbook-plantuml -l"

Change log

0.8.0 (2022-07-04)

0.7.0 (2020-08-29)

0.6.0-beta (2020-01-29)

0.5.0 (2019-11-08)

0.4.0 (2019-09-25)

0.3.0 (2019-08-29)

0.2.0 (2019-07-08)

0.1.0 (2019-07-08)