DOCSEARCHbyAlgolia
Submit Docs

merman

repository·main·Indexed 19 days ago

https://github.com/latias94/merman

A high-performance, parity-focused Rust implementation of Mermaid.js. It provides a headless pipeline to parse, analyze, and render Mermaid diagrams into SVG, images, text, and JSON without requiring a JavaScript runtime or browser. The project includes specialized crates such as merman-analysis for diagram and Markdown analysis, manatee for headless compound graph layout (COSE-Bilkent and FCoSE), and dugong for Dagre-compatible graph layout algorithms.

Tokens
515.6K
Snippets
1.2K
Records
2.3K
Agent score
58%

What's inside merman

  1. Overview of Merman capabilities and packages

    main

    Merman is a Rust implementation of Mermaid-compatible parsing, layout, and headless rendering. It uses typed semantic and render models internally while maintaining compatibility with JSON and adapter contracts for public surfaces.

    Core Capability Areas

    • merman-core: Handles detection, preprocessing, configuration merging, parsing, sanitization, compatibility semantic JSON, parser-backed editor facts, and typed render model projection.
    • merman-render: Manages layout models, SVG parity renderers, root viewport handling, theme/config projection, text measurement, and render pipeline internals.
    • merman-ascii: Provides terminal rendering adapters and ASCII-specific layout/routing.
    • merman: The public Rust facade for parse, layout, render, and raster operations.
    • Adapters: Includes merman-cli, FFI, UniFFI, WASM, and platform wrappers that act as adapters over the canonical headless operations.
    • xtask: Used for fixture import, upstream parity comparison, generated data, audit reports, and release gates.

  2. Use ZenUML SVG assets in Merman

    main
    Merman provides vendored SVG assets from @zenuml/core (version 3.50.1) to be used by the headless ZenUML SVG renderer. These assets are normalized for stable Rust include_str! paths. While the file names are modified for compatibility with Rust's inclusion mechanism, the SVG content itself remains identical to the upstream release. These assets are licensed under the MIT license.

  3. Scope of roughr-merman operations

    main

    The roughr-merman crate is strictly a generator of operation sets. It produces the mathematical descriptions for:

    • Lines
    • Curves
    • Arcs
    • Polygons
    • Ellipses
    • SVG paths

    Note: This crate does not provide a canvas, a raster backend, or a UI framework. It is not a standalone drawing product; it is a dependency used to generate the operations required for Mermaid-compatible SVG rendering.

  4. Merman VS Code extension features and capabilities

    main

    The Merman VS Code extension provides several semantic authoring and utility features:

    • Semantic Authoring:
      • Context-sensitive completions and snippets via LSP.
      • Hover information and symbol/reference support.
      • Rename capabilities.
      • Diagnostics and automated fixes (linting).
    • Source Selection: Fence-aware selection for diagrams embedded within Markdown files.
    • Rendering & Export:
      • Secure webview preview using merman-cli.
      • Exporting diagrams to SVG, PNG, or PDF formats.
      • Copying rendered diagrams to the clipboard.
    • Binary Management: A shared binary resolver that manages the merman-lsp and merman-cli binaries, preferring package-local release binaries for a local-first experience.

  5. Understand Merman Render Assets

    main

    The merman-render crate utilizes two types of assets for rendering support: runtime files for measurement audits and embedded symbols for visual rendering.

    • KaTeX Probe: The file katex_flowchart_probe.cjs is a runtime file used by the optional Node.js KaTeX probe. It is loaded relative to CARGO_MANIFEST_DIR to perform HTML and math measurement audits.
    • ZenUML Symbols: The zenuml/*.svg files are source-backed ZenUML symbols. These are embedded directly into the Rust library at compile time using include_str!.

  6. System-Wide Impact of Layout and Rendering Changes

    main

    Changes to the core layout and rendering logic have broad implications across the project:

    ComponentImpact
    Parser/ModelC4 argument representation and invalid-input behavior changes. Requires migration to typed contracts.
    Layout (Dugong)As shared infrastructure, changes affect State, Class, Requirement, ER, and Dagre-backed Flowchart.
    RenderingShared label geometry affects multiple SVG families. Coordinate frames remain at adapter boundaries.
    ToolingCompare reports now include semantic identity and world-space geometry.
    Browser PresentationComputed CSS is still managed by playground/tests/render.presentation.spec.ts. Raw Rust comparison does not claim computed-style evidence.
    FixturesSigned upstream evidence is immutable. Local snapshots and residual catalogs change only after gates pass.

  7. Compare Satteri Mermaid and Merman Node/N-API implementations

    main

    This research report compares the @xingwangzhe/satteri-mermaid@0.7.1 package with the current private merman-node / @mermanjs/node candidates.

    Key Differences:

    • Satteri Mermaid: A narrow, synchronous SSG (Static Site Generator) plugin designed for Satteri/Astro. It uses a single render() function via napi-rs to wrap mermaid-rs-renderer. It is optimized for simple, one-off trusted static blog builds where a small synchronous API is preferred.
    • Merman Node: A broad, general-purpose Mermaid Node SDK. It supports a much larger catalog of diagram families (41 entries vs Satteri's 23), provides async/sync SVG helpers, semantic/layout/planning operations, math rendering, and advanced resource management (concurrency, bounded queues, and cancellation).

  8. Choose the right Merman integration surface

    main

    Merman provides different packages and interfaces depending on your runtime (Browser, Node.js, Rust) and your specific workflow (Analysis, Rendering, Editor support).

    HostRecommended surfaceBoundary
    Browser or Web Worker, analysis only@mermanjs/web-analysisDetection, validation, facts, and diagnostics without SVG, ASCII, or editor sessions
    Browser application with several Merman workflows@mermanjs/webOne complete browser artifact for rendering, analysis, ASCII, and editor APIs
    Node.js, CI, or static-site automationmerman-cli child processSupported browserless process boundary; JSON analysis is available
    Generic editor or LSP clientmerman-lspLanguage intelligence only; preview rendering remains separate
    VS CodeMerman VS Code extensionLocal LSP plus optional preview, export, diagnostics, and source actions
    Rust applicationmerman-analysis, merman-editor-core, or mermanIn-process typed APIs selected by capability

    Note: The browser package group on the current branch may still be a source candidate. Consult the browser package guide before assuming that a candidate package is available on npm.

  9. Reference third-party components used in Merman

    main

    Merman incorporates various third-party libraries, many of which are translated into Rust or modified to provide specific rendering behaviors (e.g., layout engines, SVG curve algorithms, or math rendering).

    Key functional areas and their dependencies include:

    • Layout Engines:
      • Dagre/Graphlib: Used via dugong for directed graph layouts.
      • CoSE (various versions): Used via manatee for CoSE layout behavior.
      • Eclipse ELK: Used via merman-elk-layered for layered algorithms.
      • FCoSE: Used via a modified Rust implementation for headless Architecture layouts.
      • Venn.js: Used via a modified Rust translation for Venn diagrams.
    • Rendering & Geometry:
      • D3-shape: Provides SVG curve algorithms (basis, natural, step, cardinal, bump, and Catmull-Rom).
      • Rough.js/rough-rs: Provides hand-drawn/sketchy aesthetics.
      • RaTeX: Provides math rendering via the ratex crate family.
      • Cytoscape.js: Provides architecture layout and styling defaults.
    • Utilities:
      • DOMPurify: Used for generating sanitizer defaults.
      • sanitize-url: Used for URL sanitization.
      • wasm-minimal-protocol: Used for Typst WASM transport.

  10. Choose the right Merman surface for your project

    main

    Merman is distributed across multiple packages depending on your target environment:

    TargetRecommended Package/Tool
    Rust Librarymerman
    CLI / CI / Docsmerman-cli
    Browser (SVG only)@mermanjs/web-render
    Full Browser Suite (Rendering, Analysis, ASCII, Editor)@mermanjs/web
    Headless Analysis (No SVG)merman-analysis
    LSP / Editor Intelligencemerman-lsp
    Other LanguagesPython, C/C++ (via FFI), Flutter/Dart, Android, or Apple
    Rustdoc / Typstmerman-rustdoc or the Typst package

  11. Understand the Merman CLI Execution Priority and Roadmap

    main

    The Merman CLI is undergoing a structured refactor to improve stability, integrity, and performance. The implementation follows a specific priority order to ensure a solid foundation before adding complex features:

    1. P0 Boundary Foundation (U1-U4): Establishes process contracts, explicit commands, bounded resource acquisition, and atomic single-file publication. This phase focuses on removing hazards like direct-truncation and pre-limit allocation.
    2. P0 Mutation Integrity (U6, U10): Focuses on safe, deterministic edits (via a new edit planner) and a recoverable transaction engine to prevent source/output corruption.
    3. P1 Execution Convergence (U5, U7, U11): Unifies render paths, separates Markdown dialects (Strict vs. Native), and integrates batch processing with the transaction engine.
    4. P1 Distribution Proof (U8): Verifies that slim artifacts (specialized binaries) work correctly and maintain their promised dependency exclusions.
    5. P2 Migration and Cleanup (U9): Removes obsolete surfaces and publishes the final migration contract.

  12. Choose a Merman Browser Package

    main

    Merman provides several specialized browser-only packages. These packages are designed for use in a browser main-thread or Web Worker. Do not use these packages for Node.js or SSR, as they require a browser realm to load the WASM module.

    PackageUse Case
    @mermanjs/webComplete browser rendering, analysis, ASCII output, and editor APIs.
    @mermanjs/web-analysisDetection, validation, facts, and semantic analysis (no SVG, ASCII, or editor sessions).
    @mermanjs/web-editorParser-backed editor sessions in a dedicated browser Worker.
    @mermanjs/web-asciiSupported ASCII diagram output.
    @mermanjs/web-renderComplete SVG-only workflow with both layouts and math.