Skip to content

KentarouTakeda/honkit-plugin-plantuml-server

Repository files navigation

HonKit PlantUML Plugin

npm version test License: MIT

PlantUML plugin for HonKit. No Java or Graphviz required .

The plugin supports APIs as follows for generating UML diagrams.

The plugin uses plantuml online server by default, so it works with zero-config .

In this case your diagram is rendered on a public server. If you care about privacy, I recommend building your own server.

Installation

  • Execute the following command.
    npm install honkit-plugin-plantuml-server
  • Write the following in book.json.
    {
      "plugins": [
        "plantuml-server"
      ]
    }

How To Use

Inline

Write a code block quote specified to the plantuml language in markdown.

For example, if you write the following in README.md.

# Introduction

```plantuml
Bob->Alice : Hello!
```

NOTE: You can also use uml / puml as the language specification.

Then it will be displayed like this.

HTML is authored for example as follows.

<figure class="plantuml">
  <img src="data:image/svg+xml;base64,........">
</figure>

NOTE: You can change the CSS class name as you like.

External file

If you specify a relative path, it will read the path relative to the original markdown. For example:

{% uml src="path/to/uml" %}
{% enduml %}

If you specify an absolute path, it will be read based on the root folder of the books defined by book.json. For example:

{% uml src="/path/to/uml" %}
{% enduml %}

NOTE: Modifications other than markdown files are not supported by honkit serve hot reload.

Configuration

Option Default Description
server http://www.plantuml.com/plantuml/ URL for rendering on your own server
format svg Supports png and svg
cacheDir os.tmpdir() Directory to cache rendered results. If null is specified, cache is not used.
cssClass plantuml CSS class name given to the rendered figure.
optimizeImage true Whether to remove metadata from rendered results

A book.json describing these would look like this, for example:

{
  "plugins": [
    "plantuml-server"
  ],
  "pluginsConfig": {
    "plantuml-server": {
      "server": "http://your-server.local/plantuml/",
      "format": "png",
      "cacheDir": "/tmp",
      "cssClass": "customClassName",
      "optimizeImage": false
    }
  }
}

Contributing and Development

$ git clone https://github.com/KentarouTakeda/honkit-plugin-plantuml-server.git
$ cd honkit-plugin-plantuml-server
$ npm install
$ npm test

License

HonKit PlantUML Plugin is open-sourced software licensed under the MIT license.