API

Public

Kroki.KrokiModule

The 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.).

source
Kroki.DiagramType
struct 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 the specification 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.

source
Kroki.DiagramMethod
Diagram(
    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.

source
Kroki.DiagramMethod
Diagram(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.

source
Kroki.overrideShowableFunction
overrideShowable(
    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!

source
Kroki.renderFunction
render(
    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.

source

Service Management

Kroki.ServiceModule

Defines 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.

Removing service container images

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 Kroki versions

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.

source
Kroki.Service.DockerComposeExecutionErrorType
struct 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
source
Kroki.Service.infoMethod
info() -> 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()

source
Kroki.Service.setEndpoint!Function
setEndpoint!() -> 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")
source
Kroki.Service.start!Function
start!()
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.

source
Kroki.Service.statusMethod
status() -> 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)
source
Kroki.Service.stop!Function
stop!()
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.

source

String Literals

The following string literals are exported from the Kroki module to make it more straightforward to instantiate Diagrams.

Kroki.StringLiteralsModule
source

Private

Kroki.DiagramTypeMetadataType
struct 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.

source
Kroki.LIMITED_DIAGRAM_SUPPORTConstant

Some 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 types.

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/pdfimage/jpegimage/pngimage/svg+xmltext/plaintext/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
source
Kroki.SHOWABLE_OVERRIDESConstant

Tracks 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.

source
Kroki.UriSafeBase64PayloadFunction
UriSafeBase64Payload(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.

source
Kroki.normalizeDiagramTypeFunction
normalizeDiagramType(diagram::Diagram) -> Symbol

Normalizes the type of the Diagram enabling consistent comparisons, etc. while enabling user-facing case insensitivity.

source

Documentation

Exceptions

Kroki.ExceptionsModule

Defines 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
source
Kroki.Exceptions.DiagramPathOrSpecificationErrorType
struct DiagramPathOrSpecificationError <: Exception

An Exception to be thrown when the path and specification keyword arguments to Diagram are not specified mutually exclusive.

Fields

  • path::Union{Nothing, AbstractString}: The path keyword argument passed to the Diagram.

  • specification::Union{Nothing, AbstractString}: The specification keyword argument passed to the Diagram.

source
Kroki.Exceptions.InvalidOutputFormatErrorType
struct InvalidOutputFormatError <: Exception

An Exception to be thrown when a Diagram is rendered 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: The Diagram that caused the error.
source
Kroki.Exceptions.UnsupportedMIMETypeErrorType
struct 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 selected MIME type that is not supported.

  • supported_mime_types::Set{MIME}: The set of supported MIME types.

source

Service Management

Kroki.Service.executeDockerComposeFunction
executeDockerCompose(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.

source

String Literals

Kroki.StringLiterals.interpolateMethod
interpolate(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. Expressions, Symbols, Strings that can be incorporated in the args of another Expression.

source
Kroki.StringLiterals.shouldInterpolateMethod
shouldInterpolate(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.

source