eleventy-plugin-plantuml
v1.1.7
Published
Eleventy (11ty) Plantuml markdown plugin
Downloads
185
Maintainers
Readme
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)
Contribute
- create a fork of this repo
- make your changes
- run prettier for code format consistency
- test your code by running
yarn test
ornpm 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.