Create diagrams through the Kroki API which unifies several diagram generation libraries.

Description

Create diagrams in multiple file formats (svg/jpeg/png/pdf/base64) based on a textual description with the help of the Kroki API.

Docker Prerequisites

Be aware that for the macro to be able to render diagrams the following are necessary:

• Docker must be installed on the machine running XWiki.
• the OS user running XWiki must be allowed to use / access the Docker engine.

Usage and Examples

Without a file format specified:

{{kroki diagramType="graphviz"}}
digraph G {Hello->World}
{{/kroki}}

Simple diagram generated with the graphviz library

With a file format specified:

{{kroki diagramType="plantuml" outputType="png"}}
skinparam monochrome true
skinparam ranksep 20
skinparam dpi 150
skinparam arrowThickness 0.7
skinparam packageTitleAlignment left
skinparam usecaseBorderThickness 0.4
skinparam defaultFontSize 12
skinparam rectangleBorderThickness 1

rectangle "Main" {
  (main.view)
  (singleton)
}
rectangle "Base" {
  (base.component)
  (component)
  (model)
}
rectangle "<b>main.ts</b>" as main_ts

(component) ..> (base.component)
main_ts ==> (main.view)
(main.view) --> (component)
(main.view) ...> (singleton)
(singleton) ---> (model)
{{/kroki}}

Diagram generated with the plantuml library

To create a diagram, you should now the syntax for the selected diagram type.

Refer to this diagram to see supported diagram types and output types.

Types of diagrams and file types supported by Kroki

Parameters Definition

Name	Optional	Allowed Values	Default Value	Description
diagramType	No	text		The service to be used to create the new diagram.
outputType	Yes	svg, png, jpeg, pdf, base64	svg	The file type of the new generated diagram.

Configuration

The Kroki Macro has a dedicated page in the Administration Section, which can be used to configure how the service works.

Kroki Configuration Section in Administration

There are 5 docker container configurations needed to support all diagram types offered by Kroki, which exist by default in the source code and they can be overwritten through the Kroki Configuration section in Administration by creating new configuration pages.
The Default container, which is used for the majority of diagram types by default has a configuration page.

The configuration page of the Default configuration

The following are the properties of a configuration:

Name	Optional	Allowed Values	Default Value	Description
CONFIGURATION NAME	No	text		The name of the configuration, can be used to overwrite properties through the xwiki.properties file.
DIAGRAM TYPES	No	List of text values separated by ", "		The diagram types for which this container is responsible.
DOCKER IMAGE	No	text		The name of the docker container image to be pulled from from Docker Hub.
CONTAINER NAME	No	text		The name to be given to the docker container.
IS CONTAINER REUSABLE	No	yes or no		No if the macro should create a new container every time a request to the macro is made, yes if the container should be reused if it exists.
HOST	Yes	domain of server hosting Kroki API		The host to which Kroki API requests should be made, only if host is empty will the macro create a container and make requests to the container.
PORT	Yes, if host is provided	16-bit positive number		The port to which requests should be made, if the configuration has a valid host then port is optional, otherwise a port is required according to the docker image to be initialized.
HEALTH CHECK PATH	Yes	text		The path to which a HTTP request should be made to check that the service is available(Ex:/graphviz/svg).
HEALTH CHECK BODY	Yes	text		The body of the health check request.
HEALTH CHECK VERB	No	an upper case HTTP verb		The HTTP action of the health check request, should be upper case(Ex:POST).
HEALTH CHECK ACCEPTED STATUS CODES	No	one or multiple HTTP status codes, betweeen 200 and 206	200	The HTTP response codes for which the service is considered available.

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

1. Log in the wiki with a user having Administration rights
2. Go to the Administration page and select the Import category
3. Follow the on-screen instructions to upload the downloaded XAR
4. Click on the uploaded XAR and follow the instructions
5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes

v1.1

Dependencies

Dependencies for this extension (org.xwiki.contrib.kroki:macro-kroki-ui 1.1):

• org.xwiki.contrib.kroki:macro-kroki-api 1.1
• org.xwiki.platform:xwiki-platform-administration-ui 13.10
• org.xwiki.platform:xwiki-platform-sheet-ui 13.10
• org.xwiki.platform:xwiki-platform-xclass-ui 13.10
• org.xwiki.platform:xwiki-platform-livetable-ui 13.10