### Local Preview Smoke Test Setup

Source: https://github.com/latias94/merman/blob/main/packages/typst/merman/README.md

Copies the built package to a preview namespace and compiles an example for smoke testing.

```sh
mkdir -p target/typst-preview/preview/merman
cp -R dist/typst/merman/0.1.0 target/typst-preview/preview/merman/
typst compile --package-path target/typst-preview \
  dist/typst/merman/0.1.0/examples/options.typ \
  target/typst-smoke/options.pdf
```

--------------------------------

### Example Usage

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/ascii-color-role-api/DESIGN.md

Example demonstrating how to configure AsciiRenderOptions with color mode and theme.

```APIDOC
## Example Usage

### Description
Example demonstrating how to configure `AsciiRenderOptions` with color mode and theme.

### Code
```rust
let options = AsciiRenderOptions::unicode()
    .with_color_mode(AsciiColorMode::TrueColor)
    .with_color_theme(
        AsciiColorTheme::default_dark()
            .with_role(AsciiColorRole::EdgeArrow, AsciiRgb::from_hex24(0x7aa2f7)),
    );
```
```

--------------------------------

### Runnable Raster Output Example

Source: https://github.com/latias94/merman/blob/main/README.md

Demonstrates how to run the raster output example using Cargo. This command shows how to pipe diagram definitions to the example for conversion into a PNG file.

```bash
cargo run -p merman --features raster --example example_05_raster_output
printf "flowchart LR
A --> B
" | \
  cargo run -p merman --features raster --example example_05_raster_output -- target/example.png
```

--------------------------------

### Install Mermaid CLI

Source: https://github.com/latias94/merman/blob/main/docs/rendering/UPSTREAM_SVG_BASELINES.md

Navigate to the mermaid-cli directory and install its dependencies.

```bash
cd tools/mermaid-cli && npm install
```

--------------------------------

### Run Built-In Examples with Merman

Source: https://github.com/latias94/merman/blob/main/crates/merman/examples/README.md

Execute Merman examples that use built-in Mermaid source. Some examples require specific features like 'render' or 'raster'. Output is directed to stdout or a specified file.

```bash
cargo run -p merman --features render --example example_01_svg_basic > out.svg
```

```bash
cargo run -p merman --example example_02_semantic_json
```

```bash
cargo run -p merman --features render --example example_03_layout_json
```

```bash
cargo run -p merman --features ascii --example example_04_ascii_output
```

```bash
cargo run -p merman --features raster --example example_05_raster_output -- target/example.png
```

```bash
cargo run -p merman --features render --example example_06_svg_pipeline > pipeline.svg
```

```bash
cargo run -p merman --features render --example example_07_theme_css > themed.svg
```

```bash
cargo run -p merman --example example_08_deterministic_gantt
```

```bash
cargo run -p merman --features render --example example_09_multiple_diagrams
```

```bash
cargo run -p merman --features egui-example --example example_10_integration_egui
```

```bash
cargo run -p merman --features render --example example_11_custom_output_environment > host-preview.svg
```

--------------------------------

### Install Web Platform Dependencies

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/web-wasm-playground/EVIDENCE_AND_GATES.md

Installs dependencies for the Merman web platform.

```bash
npm ci --prefix platforms/web
```

--------------------------------

### Quickstart Merman Library Usage

Source: https://github.com/latias94/merman/blob/main/README.md

Basic example of using Merman's HeadlessRenderer in Rust to render an SVG diagram.

```rust
use merman::render::HeadlessRenderer;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let renderer = HeadlessRenderer::new().with_diagram_id("readme-example");
    let svg = renderer
        .render_svg_sync("flowchart TD
A[Start] --> B[Done]")?
        .unwrap();

    println!("{svg}");
    Ok(())
}
```

--------------------------------

### Runnable SVG Pipeline Example

Source: https://github.com/latias94/merman/blob/main/README.md

Demonstrates running SVG pipeline examples using Cargo. These commands show how to generate SVG output from diagram definitions, with one example focusing on custom output environments.

```bash
cargo run -p merman --features render --example example_06_svg_pipeline < fixtures/flowchart/basic.mmd > out.svg
cargo run -p merman --features render --example example_11_custom_output_environment > host-preview.svg
```

--------------------------------

### Run Merman Smoke Example

Source: https://github.com/latias94/merman/blob/main/docs/bindings/APPLE_SWIFT.md

Builds the Apple xcframework and runs the Merman Swift smoke example application.

```bash
bash scripts/build-apple-xcframework.sh
swift run --package-path platforms/apple/examples/smoke MermanAppleSmoke
```

--------------------------------

### PowerShell Example: Create and Render SVG

Source: https://github.com/latias94/merman/blob/main/README.md

This PowerShell example demonstrates creating a Mermaid diagram file and then rendering it to SVG using the Merman CLI. It's equivalent to the bash example but uses PowerShell syntax for file creation.

```powershell
@'\nflowchart TD\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Do thing]\n  B -->|No| D[Do other thing]\n'@ | Set-Content -Encoding utf8 example.mmd

merman-cli render example.mmd --out example.svg
```

--------------------------------

### Quadrant Chart Docs Example (Config + Theme Variables)

Source: https://github.com/latias94/merman/blob/main/docs/alignment/QUADRANTCHART_UPSTREAM_TEST_COVERAGE.md

A documentation example for quadrant charts showing configuration and theme variable usage.

```mermaid
docs example (config + themeVariables): fixtures/quadrantchart/upstream_quadrant_docs_config_and_theme_example.mmd
```

--------------------------------

### Install Playground Dependencies

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/web-wasm-playground/EVIDENCE_AND_GATES.md

Installs dependencies for the Merman playground.

```bash
npm ci --prefix playground
```

--------------------------------

### Install and Build Web Package

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/web-wasm-playground/EVIDENCE_AND_GATES.md

Installs dependencies and builds the web package for the merman-wasm project.

```bash
npm install --prefix platforms/web
npm run build --prefix platforms/web
npm run prepack --prefix platforms/web
(cd platforms/web && npm pack --dry-run)
```

--------------------------------

### Quadrant Chart Docs Example (Point Styling)

Source: https://github.com/latias94/merman/blob/main/docs/alignment/QUADRANTCHART_UPSTREAM_TEST_COVERAGE.md

A documentation example for quadrant charts demonstrating point styling.

```mermaid
docs example (point styling): fixtures/quadrantchart/upstream_quadrant_docs_styling_example.mmd
```

--------------------------------

### Install, Build, and Prepack Web Package

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/web-wasm-playground/JOURNAL/2026-06-01-wwp-030.md

Installs dependencies, builds the web package, runs prepack checks, and performs a dry run of the npm pack command. Also includes commands to check code formatting and diffs.

```bash
npm install --prefix platforms/web
npm run build --prefix platforms/web
npm run prepack --prefix platforms/web
cd platforms/web && npm pack --dry-run
cargo fmt --check
git diff --check
```

--------------------------------

### Minimal End-to-End Example: Create and Render SVG

Source: https://github.com/latias94/merman/blob/main/README.md

A minimal example demonstrating how to create a Mermaid diagram in a file and then render it to an SVG using the CLI. This covers basic diagram creation and SVG output.

```bash
cat > example.mmd <<'EOF'\nflowchart TD\n  A[Start] --> B{Decision}\n  B -->|Yes| C[Do thing]\n  B -->|No| D[Do other thing]\nEOF'\n
merman-cli render example.mmd --out example.svg
```

--------------------------------

### Generate ASCII Output Example (Unicode)

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/ascii-renderer-productization/EVIDENCE_AND_GATES.md

Runs an example to generate the default Unicode sequence output using the ASCII feature.

```bash
cargo run -p merman --features ascii --example ascii_output
```

--------------------------------

### Run Merman Example with Render Feature

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/host-styling-svg-postprocessors/EVIDENCE_AND_GATES.md

Executes the `svg_pipeline` example with the `render` feature enabled, piping input from a file.

```powershell
Get-Content fixtures\flowchart\basic.mmd | cargo run -q -p merman --features render --example svg_pipeline
```

--------------------------------

### Minimal End-to-End Example: Render ASCII

Source: https://github.com/latias94/merman/blob/main/README.md

This minimal example shows how to render a predefined Mermaid diagram to ASCII text format using the CLI. It's a quick way to preview diagrams in text-based environments.

```bash
merman-cli render --format ascii example.mmd
```

--------------------------------

### Generate ASCII Output Example (Pure ASCII)

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/ascii-renderer-productization/EVIDENCE_AND_GATES.md

Runs an example to generate the sequence output using pure ASCII characters with the ASCII feature.

```bash
cargo run -p merman --features ascii --example ascii_output -- --ascii
```

--------------------------------

### Compile and Run render_svg Example (macOS/Linux)

Source: https://github.com/latias94/merman/blob/main/crates/merman-ffi/README.md

Command to compile the render_svg C example and link it against the merman-ffi library. This command sets up include paths, library paths, and runtime paths.

```sh
cargo build -p merman-ffi --release
cc -I crates/merman-ffi/include \
  crates/merman-ffi/examples/render_svg.c \
  -L target/release -lmerman_ffi \
  -Wl,-rpath,"$PWD/target/release" \
  -o target/merman-ffi-render-svg
target/merman-ffi-render-svg
```

--------------------------------

### Install merman-cli from Local Checkout

Source: https://github.com/latias94/merman/blob/main/crates/merman-cli/README.md

Installs the merman-cli directly from a local source code checkout using Cargo.

```sh
cargo install --path crates/merman-cli
```

--------------------------------

### Run RaTeX Math Audit Example

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/fearless-refactor/RATEX_MATH_AUDIT.md

Execute the merman-render crate with the `ratex-math` feature to run the math audit example. This command is used to reproduce issues and test math rendering.

```bash
cargo run -p merman-render --features ratex-math --example ratex_math_audit
```

--------------------------------

### Run Raster Output Example

Source: https://github.com/latias94/merman/blob/main/README.md

Executes a Rust example to generate raster (e.g., PNG, SVG) output for diagrams. This command requires the `raster` feature to be enabled.

```bash
cargo run -p merman --features raster --example example_05_raster_output
```

--------------------------------

### Run Example Smoke Test

Source: https://github.com/latias94/merman/blob/main/docs/bindings/PYTHON_UNIFFI.md

This command executes a smoke test script located in the examples directory after the Python package has been generated. Ensure PYTHONPATH is set correctly.

```bash
PYTHONPATH=platforms/python/merman/src python platforms/python/merman/examples/smoke.py
```

--------------------------------

### Direct Rendering Example

Source: https://github.com/latias94/merman/blob/main/crates/merman-render/README.md

Demonstrates how to use merman-render to parse a diagram, perform layout, and render it to an SVG string. This example uses the `headless_svg_defaults` for layout options and applies a `resvg_safe` pipeline for rasterization compatibility.

```rust
use merman_core::{Engine, ParseOptions};
use merman_render::{layout_parsed_render_layout_only, LayoutOptions};
use merman_render::svg::{
    render_layout_svg_parts_for_render_model_with_config,
    SvgPipeline,
    SvgRenderOptions,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = Engine::new();
    let parsed = engine
        .parse_diagram_for_render_model_sync(
            "flowchart TD\nA[API] --> B[DB]",
            ParseOptions::strict(),
        )?
        .expect("diagram detected");

    let layout_options = LayoutOptions::headless_svg_defaults();
    let layout = layout_parsed_render_layout_only(&parsed, &layout_options)?;

    let svg_options = SvgRenderOptions {
        diagram_id: Some("example-diagram".to_string()),
        ..SvgRenderOptions::default()
    };

    let svg = render_layout_svg_parts_for_render_model_with_config(
        &layout,
        &parsed.model,
        &parsed.meta.effective_config,
        parsed.meta.title.as_deref(),
        layout_options.text_measurer.as_ref(),
        &svg_options,
    )?;

    let svg = SvgPipeline::resvg_safe().process_to_string(&svg)?;
    println!("{svg}");

    Ok(())
}
```

--------------------------------

### Run Smallest Current Repro

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/ascii-sequence-rect-par-over/EVIDENCE_AND_GATES.md

Executes the smallest reproducible example for the sequence_rect_par_over tests.

```bash
cargo nextest run -p merman-ascii sequence_rect_par_over
```

--------------------------------

### MermanEngine Initialization and Basic Usage

Source: https://github.com/latias94/merman/blob/main/platforms/python/merman/README.md

Demonstrates how to initialize the MermanEngine, check ABI version, print package version, and perform basic rendering and parsing operations.

```APIDOC
## MermanEngine Initialization and Basic Usage

### Description
Initializes the MermanEngine, checks its ABI version, and prints the package version. It also shows examples of rendering diagrams to SVG and ASCII text, parsing to JSON, computing layout JSON, and validating diagram sources.

### Methods
- `merman.MermanEngine()`: Initializes the Merman engine.
- `engine.abi_version()`: Returns the ABI version of the engine.
- `engine.package_version()`: Returns the package version of the engine.
- `engine.render_svg(source: str, options_json: str | None)`: Renders a Mermaid diagram source to an SVG string.
- `engine.render_ascii(source: str, options_json: str | None)`: Renders a Mermaid diagram source to an ASCII text string.
- `engine.parse_json(source: str, options_json: str | None)`: Parses a Mermaid diagram source into a semantic JSON representation.
- `engine.layout_json(source: str, options_json: str | None)`: Computes the layout JSON for a Mermaid diagram source.
- `engine.validate(source: str, options_json: str | None)`: Validates a Mermaid diagram source.
- `engine.supported_diagrams()`: Returns a list of supported diagram types.
- `engine.supported_themes()`: Returns a list of supported themes.
- `engine.supported_host_theme_presets()`: Returns a list of supported host theme presets.

### Parameters
- `source` (str): The Mermaid diagram source code.
- `options_json` (str | None): An optional JSON string containing parsing, layout, and SVG options. Pass `None` for default options.

### Error Handling
- `merman.MermanError.Binding`: Catches errors related to the binding, providing `code_name` and `message` attributes.
```

--------------------------------

### Build Custom Host Output Environment

Source: https://github.com/latias94/merman/blob/main/README.md

This example uses the `render` feature to build a custom output environment for a host application. It's useful for creating tailored rendering pipelines.

```bash
cargo run -p merman --features render --example example_11_custom_output_environment > host-preview.svg
```

--------------------------------

### Integrate with egui GUI Host

Source: https://github.com/latias94/merman/blob/main/README.md

This example demonstrates integrating Merman with a desktop GUI host using egui, leveraging the `egui-example` feature. It serves as a skeleton for building custom host applications.

```bash
cargo run -p merman --features egui-example --example example_10_integration_egui
```

--------------------------------

### Install wasm-bindgen-cli

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/web-wasm-playground/JOURNAL/2026-06-01-wwp-020.md

Install the `wasm-bindgen-cli` tool with a locked version, necessary for WASM compilation.

```bash
cargo install wasm-bindgen-cli --version 0.2.108 --locked
```

--------------------------------

### Install merman-cli with Cargo

Source: https://github.com/latias94/merman/blob/main/crates/merman-cli/README.md

Installs the merman-cli using the Rust package manager, Cargo.

```sh
cargo install merman-cli
```

--------------------------------

### Subgraph TD Direction Example

Source: https://github.com/latias94/merman/blob/main/crates/merman-ascii/tests/testdata/mermaid-ascii/ascii/subgraph_td_direction.txt

This example demonstrates a subgraph with a top-down direction in Merman ASCII.

```mermaid
graph TD
subgraph one
    A --> B
end
```

--------------------------------

### Initialize and Use MermanEngine in Swift

Source: https://github.com/latias94/merman/blob/main/platforms/apple/README.md

Demonstrates initializing the MermanEngine and using its methods to render SVG, parse JSON, and retrieve metadata. Includes an example of error handling for rendering operations.

```swift
import Merman

let engine = try MermanEngine()
let source = "flowchart TD\nA[Hello] --> B[World]"
let version = engine.packageVersion

let svg = try engine.renderSvg(
    source,
    optionsJson: #"{"svg":{"pipeline":"readable"}}"#
)
let semanticJson = try engine.parseJsonRaw(source)
let layoutJson = try engine.layoutJsonRaw(source)
let ascii = try engine.renderAscii(source)
let validation = try engine.validate(source)
let diagrams = try engine.supportedDiagrams()
let themes = try engine.supportedThemes()
let hostThemePresets = try engine.supportedHostThemePresets()

do {
    _ = try engine.renderSvg(source, optionsJson: "{")
} catch MermanError.binding(_, let codeName, let message) {
    print("\(codeName): \(message)")
}
```

--------------------------------

### Install Merman Python Package

Source: https://github.com/latias94/merman/blob/main/README.md

Install the Merman Python package using pip. This package is experimental.

```sh
# Python package (experimental UniFFI wheels)
pip install merman
```

--------------------------------

### Install Merman Web Package

Source: https://github.com/latias94/merman/blob/main/README.md

Install the Merman package for browser or TypeScript environments using npm.

```sh
# Browser / TypeScript package
npm install @mermanjs/web
```

--------------------------------

### Quadrant Chart Docs Example (Reach/Engagement)

Source: https://github.com/latias94/merman/blob/main/docs/alignment/QUADRANTCHART_UPSTREAM_TEST_COVERAGE.md

A documentation example for quadrant charts focusing on reach and engagement.

```mermaid
docs example (reach/engagement): fixtures/quadrantchart/upstream_quadrant_docs_example_reach_engagement.mmd
```

--------------------------------

### Quadrant Chart Parser Spec Example (Header Only)

Source: https://github.com/latias94/merman/blob/main/docs/alignment/QUADRANTCHART_UPSTREAM_TEST_COVERAGE.md

Example of a quadrant chart with only a header, from the Jison spec.

```mermaid
header only: fixtures/quadrantchart/upstream_quadrant_header_only_jison_spec.mmd
```

--------------------------------

### Install @mermanjs/web Package

Source: https://github.com/latias94/merman/blob/main/crates/merman-wasm/README.md

For most browser and TypeScript applications, install the `@mermanjs/web` package instead of depending on this crate directly.

```sh
npm install @mermanjs/web
```

--------------------------------

### Initialize and Render with Merman Swift API

Source: https://github.com/latias94/merman/blob/main/docs/bindings/APPLE_SWIFT.md

Demonstrates initializing the Merman engine and rendering diagrams to SVG and ASCII formats using the Swift API. Also shows parsing and layout of JSON, validation, and listing supported diagrams.

```swift
import Merman

let engine = try MermanEngine()
let svg = try engine.renderSvg("flowchart TD\nA[Hello] --> B[World]")
let ascii = try engine.renderAscii("flowchart TD\nA[Hello] --> B[World]")
let semanticJson = try engine.parseJsonRaw("flowchart TD\nA[Hello] --> B[World]")
let layoutJson = try engine.layoutJsonRaw("flowchart TD\nA[Hello] --> B[World]")
let validation = try engine.validate("flowchart TD\nA[Hello] --> B[World]")
let diagrams = try engine.supportedDiagrams()
```

--------------------------------

### Troubleshooting: `include_mmd!` Path Example

Source: https://github.com/latias94/merman/blob/main/crates/merman-rustdoc/README.md

Provides an example of how a path within a crate resolves to a specific file location.

```text
my-crate/docs/architecture.mmd
```

--------------------------------

### Run Flowchart Debug SVG Example

Source: https://github.com/latias94/merman/blob/main/docs/rendering/FLOWCHART_DEBUG_SVG.md

Execute the flowchart_debug_svg example using cargo to generate an SVG output from a Mermaid file.

```bash
cargo run -p merman-render --example flowchart_debug_svg < fixtures/flowchart/basic.mmd > out.svg
```

--------------------------------

### Initialize Merman and Render Diagrams

Source: https://github.com/latias94/merman/blob/main/platforms/flutter/README.md

Opens the Merman engine and demonstrates rendering SVG, parsing JSON, computing layout, and validating Mermaid source. Includes error handling for invalid options.

```dart
import 'package:merman/merman.dart';

final merman = Merman.open();
final source = 'flowchart TD
A[Hello] --> B[World]';
final version = merman.packageVersion;

final svg = merman.renderSvg(
  source,
  optionsJson: '{"svg":{"pipeline":"readable"}}',
);
final semantic = merman.parseJson(source);
final layout = merman.layoutJson(source);
final ascii = merman.renderAscii(source);
final validation = merman.validate(source);
final diagrams = merman.supportedDiagrams();
final themes = merman.supportedThemes();
final hostThemePresets = merman.supportedHostThemePresets();

try {
  merman.renderSvg(source, optionsJson: '{');
} on MermanException catch (error) {
  print('${error.codeName}: ${error.message}');
}
```

--------------------------------

### Generate and Verify Default Configuration

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/pie-11-15-parity/EVIDENCE_AND_GATES.md

Generates the default configuration and then verifies it using the 'xtask' command.

```bash
cargo run -p xtask -- gen-default-config

```

```bash
cargo run -p xtask -- verify-default-config

```

--------------------------------

### Prepack Web Platform

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/web-wasm-playground/EVIDENCE_AND_GATES.md

Prepacks the web platform for Merman.

```bash
npm run prepack --prefix platforms/web
```

--------------------------------

### Quadrant Chart Parser Spec Example (Whole Chart Basic)

Source: https://github.com/latias94/merman/blob/main/docs/alignment/QUADRANTCHART_UPSTREAM_TEST_COVERAGE.md

Example of a whole quadrant chart with basic points, from the Jison spec.

```mermaid
whole chart (basic points): fixtures/quadrantchart/upstream_quadrant_whole_chart_jison_spec.mmd
```

--------------------------------

### Quadrant Chart Parser Spec Example (Missing Side Appends)

Source: https://github.com/latias94/merman/blob/main/docs/alignment/QUADRANTCHART_UPSTREAM_TEST_COVERAGE.md

Example of a quadrant chart where missing right/top sides append '?' to left/bottom.

```mermaid
missing right/top side appends ` ? ` to left/bottom: fixtures/quadrantchart/upstream_quadrant_axes_missing_side_jison_spec.mmd
```

--------------------------------

### Build Merman Web Package

Source: https://github.com/latias94/merman/blob/main/platforms/web/README.md

Install dependencies, build the package, and run a smoke test for the web integration.

```sh
npm install --prefix platforms/web
npm run build --prefix platforms/web
npm run smoke --prefix platforms/web
```

--------------------------------

### Run Dagre Reference Adapter with Basic Fixture

Source: https://github.com/latias94/merman/blob/main/docs/workstreams/headless-parity-deepening/JOURNAL/2026-06-02-hpd-050-dagre-reference-adapter.md

Compares Dagre layout using the 'basic' fixture and outputs results to a specified directory. This command is part of the verification process for the Dagre reference adapter.

```bash
cargo run -p xtask -- compare-dagre-layout --fixture basic --out-dir target\compare\dagre-layout-hpd050-reference-adapter
```