Skip to content

Mermaid rendering backends

c4.renderers.mermaid.renderer.MermaidRenderer

A renderer for converting a Diagram object into Mermaid syntax.

__init__ 

__init__(
    render_options: MermaidRenderOptions | None = None,
    backend: BaseMermaidBackend | None = None,
) -> None

Parameters:

Name Type Description Default
render_options MermaidRenderOptions | None

Render options that controls diagram rendering behavior, such as direction, spacing, and group alignment.

 None

render 

render(diagram: _TDiagram) -> str

Render the given Diagram into Mermaid format.

Parameters:

Name Type Description Default
diagram _TDiagram

The diagram to render.

 required

Returns:

Type Description
str

A Mermaid-formatted string representing the diagram.

render_bytes 

render_bytes(
    diagram: _TDiagram, *, format: DiagramFormat
) -> bytes

Render a Diagram and return the result as raw bytes.

This method first converts the Diagram into Mermaid source text and then delegates the actual rendering to the configured Mermaid backend.

Parameters:

Name Type Description Default
diagram _TDiagram

The diagram instance to render.

 required
format DiagramFormat

Output format of the rendered diagram.

 required

Returns:

Type Description
bytes

The rendered diagram content as raw bytes.

Raises:

Type Description
MermaidBackendConfigurationError

If no Mermaid backend is configured for this renderer.
MermaidError

If the underlying Mermaid backend fails to render the diagram.

render_file 

render_file(
    diagram: _TDiagram,
    output_path: str | Path,
    *,
    format: DiagramFormat,
    overwrite: bool = True,
) -> Path

Render a Diagram and write the result to a file.

This method first converts the Diagram into Mermaid source text and then delegates file generation to the configured Mermaid backend.

Parameters:

Name Type Description Default
diagram _TDiagram

The diagram instance to render.

 required
output_path str | Path

Path where the rendered diagram should be written.

 required
format DiagramFormat

Output format of the rendered diagram.

 required
overwrite bool

Whether to overwrite the output file if it already exists.

 True

Returns:

Type Description
Path

Path to the written output file.

Raises:

Type Description
MermaidBackendConfigurationError

If no Mermaid backend is configured for this renderer.
FileExistsError

If the output file exists and overwrite is set to False.
MermaidError

If the underlying Mermaid backend fails to render or write the diagram.

c4.renderers.mermaid.backends.BaseMermaidBackend

Generate Mermaid diagrams from plain text.

A generator takes a Mermaid diagram text and produces image bytes (or writes them to a file).

to_bytes abstractmethod 

to_bytes(
    diagram: str, *, format: DiagramFormat = PNG
) -> bytes

Generate a Mermaid diagram and return the generated image as bytes.

Parameters:

Name Type Description Default
diagram str

Mermaid diagram source text.

 required
format DiagramFormat

Output image format (for example, 'svg' or 'png').

 PNG

Returns:

Type Description
bytes

Rendered image content as raw bytes.

Raises:

Type Description
MermaidRenderingError

If rendering fails.

to_file 

to_file(
    diagram: str,
    output_path: str | Path,
    *,
    format: DiagramFormat | None = PNG,
    overwrite: bool = True,
) -> Path

Generate a Mermaid diagram and write the generated image to a file.

Parameters:

Name Type Description Default
diagram str

Mermaid diagram source text.

 required
output_path str | Path

Path where the rendered image should be written.

 required
format DiagramFormat | None

Output image format. If None, the format is inferred from output_path suffix.

 PNG
overwrite bool

Whether to overwrite the output file if it already exists.

 True

Returns:

Type Description
Path

Path to the written output file.

Raises:

Type Description
ValueError

If format is None and the output path has no suffix.
FileExistsError

If the output file exists and overwrite is False.
MermaidRenderingError

If rendering fails.

c4.renderers.mermaid.backends.LocalMermaidBackend

Bases: BaseMermaidBackend

Generate Mermaid diagrams using local mermaid-cli.

Env vars
  • MERMAID_BIN: executable name/path (default: 'mmdc')

__init__ 

__init__(
    *,
    mermaid_bin: Maybe[str | None] = MISSING,
    timeout_seconds: Maybe[float] = MISSING,
    mermaid_args: Sequence[str] = (),
    env: Mapping[str, str] | None = None,
) -> None