API
Public
Kroki.Kroki
— ModuleThe main Module
containing the necessary types of functions for integration with a Kroki service.
Defines Base.show
and corresponding Base.showable
methods for different output formats and Diagram
types, so they render in their most optimal form in different environments (e.g. the documentation system, Documenter output, Pluto, Jupyter, etc.).
Kroki.Diagram
— Typestruct Diagram
A representation of a diagram that can be rendered by a Kroki service.
Examples
julia> Kroki.Diagram(:PlantUML, "Kroki -> Julia: Hello Julia!")
┌─────┐ ┌─────┐
│Kroki│ │Julia│
└──┬──┘ └──┬──┘
│ Hello Julia! │
│───────────────>│
┌──┴──┐ ┌──┴──┐
│Kroki│ │Julia│
└─────┘ └─────┘
Fields
options::Dict{String, String}
: Options to modify the appearance of thespecification
when rendered.Valid options depend on the
type
of diagram. See Kroki's website for details.The keys are case-insensitive. All specified options are passed through to Kroki, which ignores unkown options.
specification::AbstractString
: The textual specification of the diagram.type::Symbol
: The type of diagram specification (e.g. ditaa, Mermaid, PlantUML, etc.). This value is case-insensitive.
Kroki.Diagram
— MethodDiagram(
type::Symbol,
specification::AbstractString;
kwargs...
) -> Diagram
Constructs a Diagram
from the specification
for a specific type
of diagram.
Passes keyword arguments through to Diagram
untouched.
Kroki.Diagram
— MethodDiagram(type::Symbol; path, specification, kwargs...)
Constructs a Diagram
from the specification
for a specific type
of diagram, or loads the specification
from the provided path
.
Specifying both keyword arguments, or neither, is invalid.
Passes any further keyword arguments through to Diagram
untouched.
Kroki.SUPPORTED_TEXT_PLAIN_SHOW_MIME_TYPES
— ConstantThe values that can be used to configure TEXT_PLAIN_SHOW_MIME_TYPE
:
text/plain; charset=utf-8
text/plain
Kroki.TEXT_PLAIN_SHOW_MIME_TYPE
— ConstantDefines the MIME type to be used when show
gets called on a Diagram
for the text/plain
MIME type.
Should be set to a variation of the text/plain
MIME type. For instance, text/plain; charset=utf-8
to enable Unicode rendering for certain diagrams, e.g. PlantUML and Structurizr.
Only a select number of variations are supported, see LIMITED_DIAGRAM_SUPPORT
and SUPPORTED_TEXT_PLAIN_SHOW_MIME_TYPES
for details.
Defaults to text/plain; charset=utf-8
.
Kroki.overrideShowable
— FunctionoverrideShowable(
output_format::MIME,
diagram_type::Symbol,
supported::Bool
) -> Bool
Overrides the behavior of Base.showable
for a specific output_format
and diagram_type
relative to what is recorded in LIMITED_DIAGRAM_SUPPORT
. The overrides are tracked through SHOWABLE_OVERRIDES
.
Note that overriding whether a diagram type is showable
for a specific output format, specifically enabling one, requires the Kroki service to support it for a diagram to properly render!
Kroki.render
— Functionrender(
diagram::Diagram,
output_format::AbstractString;
options
) -> Any
Renders a Diagram
through a Kroki service to the specified output format.
Allows the specification of diagram options through the options
keyword. The options
default to those specified on the Diagram
.
If the Kroki service responds with an error, throws an InvalidDiagramSpecificationError
or InvalidOutputFormatError
if a known type of error occurs. Other errors (e.g. HTTP.ExceptionRequest.StatusError
for connection errors) are propagated if they occur.
SVG output is supported for all Diagram
types. See the support table for an overview of other supported output formats per diagram type and overrideShowable
in case it is necessary to override default Base.show
behavior, e.g. to disable a specific output format.
Kroki.resetShowableOverrides
— FunctionresetShowableOverrides() -> Dict{Tuple{Symbol, MIME}, Bool}
Resets SHOWABLE_OVERRIDES
so that the default showable
support is enabled for all diagram types.
Service Management
Kroki.Service
— ModuleDefines functions and constants managing the Kroki service the rest of the package uses to render diagrams. These services can be either local or remote.
This module also enables management of a local service instance, provided Docker and Docker Compose are available on the system.
Functions for removing container images that have been downloaded are not included. It will be necessary to manually clean up the container images retrieved by the service management functions.
By default, the functions managing locally running services will rely on the latest
tag for the yuzutech/kroki
container image. This typically means the most recently released version of Kroki will be used. In this mode, Kroki.Service.update!
can be used to pull in the most recent version. A KROKI_CONTAINER_IMAGE_TAG
environment variable can be configured, prior to invoking Kroki.Service.start!
, to start the services corresponding to a specific version of Kroki. It is important the variable matches an existing tag for the container image.
Changing the KROKI_CONTAINER_IMAGE_TAG
environment variable after calling Kroki.Service.start!
may result in manual cleanup of containers being necessary as the service management functions will not keep track of which versions of services were previously started.
Kroki.Service.DockerComposeExecutionError
— Typestruct DockerComposeExecutionError <: Exception
A specialized Exception
to include reporting instructions for specific types of errors that may occur while trying to execute docker-compose
.
Fields
message::String
Kroki.Service.info
— Methodinfo() -> Markdown.MD
Provides an overview of the (versions of) tools supporting the different diagram types based on information provided by the service as configured through setEndpoint!
.
Example
julia> Kroki.Service.info()
Kroki.Service.setEndpoint!
— FunctionsetEndpoint!() -> String
setEndpoint!(endpoint::AbstractString) -> Any
Sets the ENDPOINT
using a fallback mechanism if no endpoint
is provided.
The fallback mechanism checks for a KROKI_ENDPOINT
environment variable specifying an endpoint (e.g. to be used across Julia instances). If this environment variable is also not present the DEFAULT_ENDPOINT
is used.
This can, for instance, be used in cases where a privately hosted instance is available or when a local service has been start!
ed.
Returns the value that ENDPOINT
got set to.
Examples
setEndpoint!()
setEndpoint!("http://localhost:8000")
Kroki.Service.start!
— Functionstart!()
start!(update_endpoint::Bool)
Starts the Kroki service components on the local system, optionally, ensuring ENDPOINT
points to them.
Pass false
to the function to prevent the ENDPOINT
from being updated. The default behavior is to update.
Kroki.Service.status
— Methodstatus() -> Any
Returns a NamedTuple
where the keys are the names of the service components and the values their corresponding 'running' state.
Examples
julia> status()
(core = true, mermaid = false)
Kroki.Service.stop!
— Functionstop!()
stop!(perform_cleanup::Bool)
Stops any running Kroki service components ensuring ENDPOINT
no longer points to the stopped service.
Cleans up left-over containers by default. This behavior can be turned off by passing false
to the function.
Kroki.Service.update!
— Methodupdate!()
Updates the Docker images for the individual Kroki service components.
String Literals
The following string literals are exported from the Kroki
module to make it more straightforward to instantiate Diagram
s.
Kroki.StringLiterals
— ModuleDefines string literals for all supported Diagram
type
s, making it more straightforward to write diagrams inline.
Exports
@actdiag_str
@blockdiag_str
@bpmn_str
@bytefield_str
@c4plantuml_str
@d2_str
@dbml_str
@diagramsnet_str
@ditaa_str
@erd_str
@excalidraw_str
@graphviz_str
@mermaid_str
@nomnoml_str
@nwdiag_str
@packetdiag_str
@pikchr_str
@plantuml_str
@rackdiag_str
@seqdiag_str
@structurizr_str
@svgbob_str
@symbolator_str
@tikz_str
@umlet_str
@vega_str
@vegalite_str
@wavedrom_str
@wireviz_str
Imports
Base
Core
DocStringExtensions
Kroki.Documentation
Kroki.StringLiterals.@actdiag_str
— MacroKroki.StringLiterals.@blockdiag_str
— MacroKroki.StringLiterals.@bpmn_str
— MacroKroki.StringLiterals.@bytefield_str
— MacroString literal for instantiating Byte Field
Diagram
s.
Kroki.StringLiterals.@c4plantuml_str
— MacroString literal for instantiating C4 with PlantUML
Diagram
s.
Kroki.StringLiterals.@d2_str
— MacroKroki.StringLiterals.@dbml_str
— MacroKroki.StringLiterals.@diagramsnet_str
— MacroString literal for instantiating diagrams.net
Diagram
s.
Kroki.StringLiterals.@ditaa_str
— MacroKroki.StringLiterals.@erd_str
— MacroKroki.StringLiterals.@excalidraw_str
— MacroString literal for instantiating Excalidraw
Diagram
s.
Kroki.StringLiterals.@graphviz_str
— MacroKroki.StringLiterals.@mermaid_str
— MacroKroki.StringLiterals.@nomnoml_str
— MacroKroki.StringLiterals.@nwdiag_str
— MacroKroki.StringLiterals.@packetdiag_str
— MacroString literal for instantiating packetdiag
Diagram
s.
Kroki.StringLiterals.@pikchr_str
— MacroKroki.StringLiterals.@plantuml_str
— MacroKroki.StringLiterals.@rackdiag_str
— MacroKroki.StringLiterals.@seqdiag_str
— MacroKroki.StringLiterals.@structurizr_str
— MacroString literal for instantiating Structurizr
Diagram
s.
Kroki.StringLiterals.@svgbob_str
— MacroKroki.StringLiterals.@symbolator_str
— MacroString literal for instantiating Symbolator
Diagram
s.
Kroki.StringLiterals.@tikz_str
— MacroKroki.StringLiterals.@umlet_str
— MacroKroki.StringLiterals.@vega_str
— MacroKroki.StringLiterals.@vegalite_str
— MacroKroki.StringLiterals.@wavedrom_str
— MacroKroki.StringLiterals.@wireviz_str
— MacroPrivate
Kroki.DiagramTypeMetadata
— Typestruct DiagramTypeMetadata
A container to associate metadata with a specific diagram type, e.g. for documentation purposes.
Fields
name::String
: A more readable name for the diagram type, if applicable.url::String
: The URL to the website/documentation of the diagram type.
Kroki.DIAGRAM_TYPE_METADATA
— ConstantAn overview of metadata for the different Diagram
type
s that can be rendered, e.g. links to the main documentation, friendly names, etc.
Kroki.LIMITED_DIAGRAM_SUPPORT
— ConstantSome MIME types are not supported by all diagram types, this constant contains all these limitations. The union of all values corresponds to all supported Diagram
type
s.
Note that SVG output is supported by all diagram types, as is reflected in the support matrix below. Only those diagram types that explicitly only support SVG output are included in this constant.
Those diagram types that support plain text output, i.e. not just rendering their specification
, support both ASCII and Unicode character sets for rendering. This is expressed using two different text/plain
MIME types. See also SUPPORTED_TEXT_PLAIN_SHOW_MIME_TYPES
.
Support Matrix
application/pdf | image/jpeg | image/png | image/svg+xml | text/plain | text/plain; charset=utf-8 | |
---|---|---|---|---|---|---|
actdiag | ✅ | ✅ | ✅ | |||
blockdiag | ✅ | ✅ | ✅ | |||
BPMN | ✅ | |||||
Byte Field | ✅ | |||||
C4 with PlantUML | ✅ | ✅ | ✅ | ✅ | ✅ | |
D2 | ✅ | |||||
DBML | ✅ | |||||
diagrams.net | ✅ | ✅ | ||||
ditaa | ✅ | ✅ | ||||
erd | ✅ | ✅ | ✅ | ✅ | ||
Excalidraw | ✅ | |||||
Graphviz | ✅ | ✅ | ✅ | ✅ | ||
Mermaid | ✅ | ✅ | ||||
nomnoml | ✅ | |||||
nwdiag | ✅ | ✅ | ✅ | |||
packetdiag | ✅ | ✅ | ✅ | |||
Pikchr | ✅ | |||||
PlantUML | ✅ | ✅ | ✅ | ✅ | ✅ | |
rackdiag | ✅ | ✅ | ✅ | |||
seqdiag | ✅ | ✅ | ✅ | |||
Structurizr | ✅ | ✅ | ✅ | ✅ | ✅ | |
Svgbob | ✅ | |||||
Symbolator | ✅ | ✅ | ||||
TikZ/PGF | ✅ | ✅ | ✅ | ✅ | ||
UMLet | ✅ | ✅ | ✅ | |||
Vega | ✅ | ✅ | ✅ | |||
Vega-Lite | ✅ | ✅ | ✅ | |||
WaveDrom | ✅ | |||||
WireViz | ✅ | ✅ |
Kroki.MIME_TO_RENDER_ARGUMENT_MAP
— ConstantMaps MIME types to the arguments that have to be passed to the render
function, which are in turned passed to the Kroki service.
Kroki.SHOWABLE_OVERRIDES
— ConstantTracks overrides that should be applied to the output format support registered in LIMITED_DIAGRAM_SUPPORT
for specific diagram types.
Typically used to disable an output format that might selected by Base.show
to render a specific diagram type to for a given display in case that produces undesired results. Can also be used to enable output formats in addition to SVG for new diagram types that support them and that may not have been added to this package's LIMITED_DIAGRAM_SUPPORT
yet.
Should be manipulated using overrideShowable
and resetShowableOverrides
.
Kroki.UriSafeBase64Payload
— FunctionUriSafeBase64Payload(diagram::Diagram) -> String
Compresses a Diagram
's specification
using zlib, turning the resulting bytes into a URL-safe Base64 encoded payload (i.e. replacing +
by -
and /
by _
) to be used in communication with a Kroki service.
See the Kroki documentation for more information.
Kroki.getDiagramTypeMetadata
— FunctiongetDiagramTypeMetadata(
diagram_type::Symbol
) -> Kroki.DiagramTypeMetadata
Retrieves the metadata for a given diagram_type
from DIAGRAM_TYPE_METADATA
, with a fallback to a generic DiagramTypeMetadata
.
Kroki.normalizeDiagramType
— FunctionnormalizeDiagramType(diagram::Diagram) -> Symbol
Normalizes the type
of the Diagram
enabling consistent comparisons, etc. while enabling user-facing case insensitivity.
Documentation
Kroki.Documentation
— ModuleContains templates and a helper macro @setupDocstringMarkup
to easily set up consistent docstring formats across modules.
Kroki.Documentation.@setupDocstringMarkup
— MacroHelper macro ensuring consistent docstring markup across modules through templating.
Exceptions
Kroki.Exceptions
— ModuleDefines all custom Exceptions
that can be thrown by different parts of the package along with their corresponding Base.showerror
overloads.
Exports
Imports
Base
Core
DocStringExtensions
Kroki.Documentation
Kroki.Exceptions.DiagramPathOrSpecificationError
— Typestruct DiagramPathOrSpecificationError <: Exception
An Exception
to be thrown when the path
and specification
keyword arguments to Diagram
are not specified mutually exclusive.
Fields
Kroki.Exceptions.InfoRetrievalError
— Typestruct InfoRetrievalError <: Exception
An Exception
to be thrown when Kroki.Service.info
cannot retrieve its information from the Kroki service configured through Kroki.Service.setEndpoint!
.
Fields
endpoint::String
: The endpoint that was queried for information about a Kroki service.
Kroki.Exceptions.InvalidDiagramSpecificationError
— Typestruct InvalidDiagramSpecificationError <: Exception
An Exception
to be thrown when a Diagram
representing an invalid specification is passed to render
.
Fields
error::String
: The error message returned by the Kroki service causing the exception to be thrown.
cause::Diagram
: TheDiagram
that caused the error.
Kroki.Exceptions.InvalidOutputFormatError
— Typestruct InvalidOutputFormatError <: Exception
An Exception
to be thrown when a Diagram
is render
ed to an unsupported or invalid output format.
Fields
error::String
: The error message returned by the Kroki service causing the exception to be thrown.
cause::Diagram
: TheDiagram
that caused the error.
Kroki.Exceptions.UnsupportedMIMETypeError
— Typestruct UnsupportedMIMETypeError <: Exception
An Exception
to be thrown when the selected_mime_type
is not an element of the set of supported_mime_types
.
Fields
selected_mime_type::MIME
: The selectedMIME
type that is not supported.supported_mime_types::Set{MIME}
: The set of supportedMIME
types.
Service Management
Kroki.Service.DEFAULT_ENDPOINT
— ConstantThe default ENDPOINT
to use, i.e. the publicly hosted version.
Kroki.Service.ENDPOINT
— ConstantThe currently active Kroki service endpoint being used.
Kroki.Service.SERVICE_DEFINITION_FILE
— ConstantPath to the Docker Compose definitions for running a local Kroki service.
Kroki.Service.executeDockerCompose
— FunctionexecuteDockerCompose(cmd::Vector{String}) -> String
Helper function for executing Docker Compose commands.
Returns captured stdout.
Throws an ErrorException
if Docker and/or Docker Compose aren't available. Throws a DockerComposeExecutionError
if any other exception occurs during execution.
String Literals
Kroki.StringLiterals.interpolate
— Methodinterpolate(specification::AbstractString) -> Vector{Expr}
Helper function implementing string interpolation to be used in conjunction with macros defining diagram specification string literals, as they do not support string interpolation by default.
Returns an array of elements, e.g. Expr
essions, Symbol
s, String
s that can be incorporated in the args
of another Expr
ession.
Kroki.StringLiterals.shouldInterpolate
— MethodshouldInterpolate(stream::IO) -> Bool
When called at the start of an expression to interpolate, checks whether the interpolation sign that triggered interpolation was escaped or not. This takes into account multiple escaped escape characters in front of an interpolation sign.