Crate merman

Expand description

Mermaid parsing and rendering through one operation-scoped facade.

Renderer owns long-lived engine defaults. Each RenderRequest describes one source, target, resource policy, and OperationControl. The request is executed synchronously by Renderer::render; SVG, ASCII, and binary output remain target-local adapters behind the same operation boundary.

The facade deliberately does not expose source-to-SVG or source-to-ASCII convenience functions. Keeping the target and its policy in a typed request makes cancellation, deadlines, resource budgets, and output ownership explicit at every call site.

§Choosing an API

Goal	Feature	Start with
Parse Mermaid or produce semantic JSON	`diagram-*` selectors, without defaults	`Engine` and `ParseOptions`
Analyze diagnostics or Markdown fences	`analysis`	`analysis::Analyzer`
Build parser-backed editor snapshots	`editor`	`editor::analyze_document_snapshot_with_shared_text`
Render Mermaid-like SVG	`svg`	`Renderer` and `RenderRequest::svg`
Render terminal-friendly text	`ascii`	`Renderer` and `RenderRequest::ascii`
Render PNG from Rust	`png`	`Renderer` and `RenderRequest::png`
Render JPEG from Rust	`jpeg`	`Renderer` and `RenderRequest::jpeg`
Render a vector PDF from Rust	`pdf`	`Renderer` and `RenderRequest::pdf`

If you already know the diagram type, use the *_with_type_sync methods on Engine to skip detection. If you need lower-level layout or SVG pipeline control, use the re-exported types under merman::svg or depend on merman-render directly.

§Features

diagram-*: compile the selected logical families and their typed models. all-diagrams selects every built-in family; these selectors do not enable outputs or engines.
analysis: render-free diagnostics, source mapping, and Markdown analysis through merman::analysis.
editor: parser-backed editor snapshots and queries through merman::editor; this implies analysis.
svg: layout plus SVG rendering through merman::svg.
ascii: ASCII/Unicode text rendering through merman::ascii.
png, jpeg, and pdf: bounded binary export through merman::svg::export; each implies svg but does not imply either of the other binary formats.
math: pure-Rust math label rendering for the SVG path; this implies svg.

The default feature set combines all-diagrams with complete-svg-elk: it supports all built-in parsers, Mermaid 12’s default ELK SVG path, deterministic rendering, the Cytoscape layout engine, and math labels without ambient system adapters. Distributed artifacts must retain the ELK implementation’s EPL-2.0 notices and source provenance. Use default-features = false with explicit family selectors and complete-svg to omit ELK, or choose individual capability leaves when you need a measured artifact closure. Neither SVG aggregate selects families.

Parser-only applications should depend on merman-core directly. If they need this facade’s re-exports instead, set default-features = false and select the required diagram-* features (or all-diagrams to retain the previous parser surface). An ordinary merman dependency intentionally compiles the complete SVG workflow.

§Quick start

use merman::{OperationControl, RenderOutput, RenderRequest, Renderer, SvgRequest};

let output = Renderer::new().render(RenderRequest::svg(
    "flowchart TD\nA[Start] --> B[Done]",
    OperationControl::new(),
    SvgRequest::default(),
))?;
let RenderOutput::Svg(Some(svg)) = output else {
    return Err("source did not contain a Mermaid diagram".into());
};
println!("{}", svg.svg());

For semantic inspection, use Renderer::prepare_semantic or a RenderTarget::Semantic request. For terminal output, use RenderTarget::Ascii. The target adapters never create a replacement operation or silently replace the caller’s cancellation handle.

§Rendering lifecycle

Merman keeps parsing, semantic preparation, target selection, and output ownership inside one operation boundary.

Re-exports§

pub use diagnostic::TerminalDiagnostic;
pub use diagnostic::TerminalDiagnosticDetails;
pub use diagnostic::TerminalRuntimePolicyError;
pub use render::AsciiRequest;
pub use render::JpegRequest;
pub use render::PngRequest;
pub use render::RasterOutput;
pub use render::OperationExecutionPath;
pub use render::RenderEvidence;
pub use render::SvgEnvironment;
pub use render::SvgLayoutOutput;
pub use render::SvgOutput;
pub use render::SvgRequest;
pub use render::PdfOutput;
pub use render::PdfRequest;
pub use render::RenderError;
pub use render::RenderOutput;
pub use render::RenderRequest;
pub use render::RenderTarget;
pub use render::Renderer;
pub use render::ResourceLimitCause;
pub use render::ResourceLimitExceeded;
pub use render::SemanticArtifact;
pub use merman_analysis as analysis;
pub use merman_editor_core as editor;

Modules§

ascii: ASCII target-local types and model-level backend interface. ASCII target-local types, capabilities, and terminal-safe diagnostic projection.
baseline: Active upstream Mermaid baseline metadata.
common
common_db
config
detect
diagnostic: Target-neutral, terminal-safe projection for parser and runtime-policy diagnostics.
diagram
diagrams: Public data models for Mermaid diagram families.
entities
error
generated
geom
models
operation: Target-neutral lifecycle primitives for CPU-bound Merman operations.
preprocess
render: Operation boundary
resources: Backend-independent Mermaid source and semantic-model resource policy.
runtime
sanitize
svg: SVG target-local types and backend capabilities. SVG target-local adapters and host-service types.
svg_security
theme_color: Source-backed color operations used by Mermaid themes and renderers.
time
utils

Structs§

BuiltInTypedRenderFamily: Canonical public identity for one compiled concrete built-in typed render family.
CapturedPanic: Non-cancellation result of one editor snapshot capture operation.
CustomJsonRenderModel: Explicit non-built-in JSON model boundary for custom parser adapters.
Detector: One diagram detector entry.
DetectorRegistry: Ordered registry that detects Mermaid diagram types.
DiagramFamilyCapability
DiagramFamilyId: Closed, catalog-owned identity for one logical Mermaid diagram family.
DiagramFamilySelector: Public Cargo selector for one logical family, regardless of this build’s availability.
DiagramHeaderFact
DiagramParseSnapshot: One preprocessing, detection, and family-construction operation for editor consumers.
DiagramRegistry: Registry for semantic JSON parsers keyed by Mermaid diagram type id.
DiagramWarningFact: Shared warning fact emitted by diagram families for analysis and lint consumers.
EditorExpectedSyntax: Parser-produced cursor context hint for completion and other editor features.
EditorFamilySemantics: Typed family semantics consumed by editor projections.
EditorSemanticDiagnostic: Parser-backed diagnostic emitted while producing editor-visible semantic facts.
EditorSemanticFacts: Parser-produced facts used by lint, completion, and LSP without exposing a public AST.
EditorSemanticSymbol: A parser-produced symbol occurrence.
Engine: Headless Mermaid parser engine.
MermaidConfig
OperationCancelled: Structured cooperative cancellation returned by an operation checkpoint.
OperationControl: Cloneable operation-scoped cooperative cancellation and deadline control.
OperationResourceLimitExceeded: Target-neutral description of a checked operation resource rejection.
OperationResourceOverride: One explicit policy override captured when a resource terminal is first recorded.
OperationResourceProvenance: Immutable policy provenance attached to the first operation resource terminal.
ParseDiagnostic: Structured parser diagnostic carried by Error::DiagramParse.
ParseMetadata: Metadata extracted before semantic diagram parsing.
ParseOptions: Parser behavior switches for model-producing parse facades.
ParsedDiagram: Parsed diagram metadata plus the Mermaid-compatible semantic JSON model.
ParsedDiagramRender: Parsed diagram metadata plus its canonically paired typed render model.
PreprocessResult
PreprocessedSource: Parser text together with an exact, composable map back to the caller’s source.
RenderDiagramRegistry: Registry for typed render-model parsers keyed by Mermaid diagram type id.
SourceSpan: Byte span attached to an editor-visible semantic fact.

Enums§

CancelReason: Why an operation stopped at a cooperative checkpoint.
CustomJsonProvenance: Origin of a custom JSON render model.
DiagramParseOutcome: Semantic result retained by one editor-facing diagram parse operation.
DiagramSnapshotCapture
EditorExpectedSyntaxKind: Parser-known syntax category that is expected at a source span.
EditorRenamePolicy: Parser-owned validation policy for renaming an entity occurrence.
EditorSemanticCompleteness: Whether editor-facing facts came from a complete family parse or a recoverable partial parse.
EditorSemanticDiagnosticKind
EditorSemanticKind: Protocol-independent symbol classification for editor-facing consumers.
EditorSemanticRole: How downstream editor indexes should project a parser-produced symbol.
Error
OperationLedgerError: Sticky terminal failure shared by operation controls and target-owned resource adapters.
OperationPhase: The broad phase in which an operation observes a terminal condition.
OperationResourceDomain: Stable adapter domain that owns an operation resource terminal.
ParseDiagnosticSpanKind
ParsedEditorFacts: Parser-backed editor facts produced by a diagram parse operation.
RenderSemanticModel: Typed semantic model used by the headless renderer.

Constants§

AGENTFLOW_CONTAINMENT_VIOLATION_WARNING_RULE_ID
AGENTFLOW_SHAPE_REMOVED_WARNING_RULE_ID
AGENTFLOW_SHAPE_UNSUPPORTED_WARNING_RULE_ID
BLOCK_WIDTH_WARNING_RULE_ID
FLOWCHART_EXPLICIT_DIRECTION_WARNING_RULE_ID
FLOWCHART_UNKNOWN_STYLE_TARGET_WARNING_RULE_ID
GIT_GRAPH_DUPLICATE_COMMIT_WARNING_RULE_ID
MAX_DIAGRAM_NESTING_DEPTH: Maximum nested diagram/include depth accepted by recursive parsers.

Traits§

BuiltinRenderSemantic: Family-owned typed semantic data that can project the public compatibility JSON contract.

Functions§

built_in_typed_render_families: Returns each compiled concrete built-in typed render-model family exactly once.
diagram_family_capabilities: Returns every known Mermaid diagram id in the pinned baseline, including unavailable ones.
diagram_family_selectors: Returns the complete catalog-owned mapping from logical families to Cargo selectors.
diagram_header_facts: Returns known header facts for Mermaid diagram starters in the pinned baseline.
diagram_type_family_id
diagram_type_family_kind
diagram_type_metadata_id
diagram_type_render_model_kind
normalize_terminal_diagnostic: Produces a bounded, terminal-safe human-readable diagnostic.
normalize_terminal_text: Normalizes untrusted authored text for terminal display without changing printable text.
preprocess_diagram
preprocess_diagram_with_known_type
supported_diagrams: Returns metadata names backed by semantic parsers compiled into this build.
supported_themes: Returns Mermaid theme names supported by the pinned baseline.

Type Aliases§

CustomJsonRenderParser: Parser used by a custom render-model registry overlay.
DiagramSemanticParser: Parser used by a custom semantic JSON registry overlay.
OperationControlResult: Result channel for a controlled operation stage.
Result

Crate merman

Crate merman Copy item path

§Choosing an API

§Features

§Quick start

§Rendering lifecycle

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate merman