eleventy-plugin-plantuml

Eleventy - Plantuml - Plugin. Uses sync request to connect to a plantuml server to convert markdown code block of type plantuml to an inline dataurl png <img>, or to svg code.

Dependencies

• eleventy A simpler static site generator for which this plugin is make.
• sync-request (for making blocking synchronous http request - not to be used in production)
• jest (for executing unit tests)
• prettier (for keeping things clean and tidy)

Installation

This plugin requires markdown syntax highlighter plugin to work.

Ensure that the Eleventy syntaxhighlight plugin is added to .eleventy.js configuration

const syntaxHighlight = require("@11ty/eleventy-plugin-syntaxhighlight");
// ...
eleventyConfig.addPlugin(syntaxHighlight);

Add plantuml plugin to configuration and optionally provide the configuration for private Plantuml server, imgClass, and output type.

const plantuml = require('eleventy-plugin-plantuml');
eleventyConfig.addPlugin(plantuml.plugin, {
  protocol: "http",
  hostname: "localhost",
  port: 8888,
  prefix: "",
  outputType: "svg",
  imgClass: "plantuml" 
});

If the server options are omitted, the plugin defaults to http://plantuml.com/plantuml server for conversion, and to PNG for output type.

Styling

By default the generated img tag will have class plantuml assigned to it. This can be overridden using options.imgClass value.

Request settings

In the rare case where control of the http request settings is required, an optional setting "request" can be added to the plugin config object which will be passed directly to the underlying request object. See https://www.npmjs.com/package/sync-request for all available settings.

const plantuml = require('eleventy-plugin-plantuml');
eleventyConfig.addPlugin(plantuml.plugin, {
  protocol: "http",
  hostname: "localhost",
  port: 8888,
  prefix: "",
  outputType: "svg",
  imgClass: "plantuml",
  request: {
      timeout: ...
      socketTimeout: ....
      retry: ...
      retryDelay: ...
      maxRetries: ...
  }
});

Using in templates

Simply create a markdown code block of type plantuml. It will be replaced by an img with inline png src (dataurl), or with svg code, depending on the value of the option outputType.

```plantuml
@startuml
!include https://raw.githubusercontent.com/bschwarz/puml-themes/master/themes/bluegray/puml-theme-bluegray.puml
participant "Makrdown Highlighter" as MDH
participant "eleventy-plugin-plantumt" as plugin
participant "Plantuml Server" as plantuml

MDH -> plugin : highlight
plugin -> plugin: compress url
plugin -> plantuml: GET /png/{url}
plantuml -> plugin: image/png
plugin -> plugin: base64
plugin -> MDH: img src="dataurl"
@enduml
```

The result is an image inserted (inline) in the generated html site (click to open)

Sequence diagram

Contribute

• create a fork of this repo
• make your changes
• run prettier for code format consistency
• test your code by running yarn test or npm test
• create a Pull Request
• Send me an email in case I miss the PR notification

Testing

Execute yarn test or npm test to execute integration tests against <plantuml.com/plantuml> live server

Test script will create an HTML file for visual inspection of generated content. The file is in a constant and by default is /tmp/eleventy-plugin-plantuml-test.html. Simply open the file in your favorite browser and ensure that four diagrams are present and look okay.