API

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

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.

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.

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.

The values that can be used to configure TEXT_PLAIN_SHOW_MIME_TYPE:

• text/plain
• text/plain; charset=utf-8

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

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!

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.

resetShowableOverrides() -> Dict{Tuple{Symbol, MIME}, Bool}

Resets SHOWABLE_OVERRIDES so that the default showable support is enabled for all diagram types.

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.

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.

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

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()

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")

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.

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)

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.

update!()

Updates the Docker images for the individual Kroki service components.

Defines string literals for all supported Diagram types, 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
• DocStringExtensions
• Kroki.Documentation

String literal for instantiating actdiag Diagrams.

String literal for instantiating blockdiag Diagrams.

String literal for instantiating BPMN Diagrams.

String literal for instantiating Byte Field Diagrams.

String literal for instantiating C4 with PlantUML Diagrams.

String literal for instantiating D2 Diagrams.

String literal for instantiating DBML Diagrams.

String literal for instantiating diagrams.net Diagrams.

String literal for instantiating ditaa Diagrams.

String literal for instantiating erd Diagrams.

String literal for instantiating Excalidraw Diagrams.

String literal for instantiating Graphviz Diagrams.

String literal for instantiating Mermaid Diagrams.

String literal for instantiating nomnoml Diagrams.

String literal for instantiating nwdiag Diagrams.

String literal for instantiating packetdiag Diagrams.

String literal for instantiating Pikchr Diagrams.

String literal for instantiating PlantUML Diagrams.

String literal for instantiating rackdiag Diagrams.

String literal for instantiating seqdiag Diagrams.

String literal for instantiating Structurizr Diagrams.

String literal for instantiating Svgbob Diagrams.

String literal for instantiating Symbolator Diagrams.

String literal for instantiating TikZ/PGF Diagrams.

String literal for instantiating UMLet Diagrams.

String literal for instantiating Vega Diagrams.

String literal for instantiating Vega-Lite Diagrams.

String literal for instantiating WaveDrom Diagrams.

String literal for instantiating WireViz Diagrams.

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.

An overview of metadata for the different Diagram types that can be rendered, e.g. links to the main documentation, friendly names, etc.

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

Maps MIME types to the arguments that have to be passed to the render function, which are in turned passed to the Kroki service.

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.

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.

getDiagramTypeMetadata(
    diagram_type::Symbol
) -> Kroki.DiagramTypeMetadata

Retrieves the metadata for a given diagram_type from DIAGRAM_TYPE_METADATA, with a fallback to a generic DiagramTypeMetadata.

normalizeDiagramType(diagram::Diagram) -> Symbol

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

Contains templates and a helper macro @setupDocstringMarkup to easily set up consistent docstring formats across modules.

Helper macro ensuring consistent docstring markup across modules through templating.

Defines all custom Exceptions that can be thrown by different parts of the package along with their corresponding Base.showerror overloads.

Exports

Imports

• Base
• DocStringExtensions
• Kroki.Documentation

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.

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

struct 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: The Diagram that caused the error.

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.

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.

The default ENDPOINT to use, i.e. the publicly hosted version.

The currently active Kroki service endpoint being used.

Path to the Docker Compose definitions for running a local Kroki service.

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.

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.

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.