tree-sitter-mermaid

A tolerant, incremental Tree-sitter grammar for Mermaid source. It provides structured concrete syntax trees and editor queries for 37 public diagram families: the original 35-family Mermaid 11.16.1 syntax baseline, plus Agentflow and Usecase from Mermaid 12.0.0. The ZenUML integration follows ZenUML Core 3.50.1. Sequence actor-menu names (link, links, properties, and details) also work as message endpoints, following the focused Mermaid 12.1.0 lexer fix without changing the other families' syntax baseline.

Use this package for syntax highlighting, syntax-aware selection, folding, and other editor features that must keep working while a document is incomplete. Use @mermanjs/web or the Merman Rust crates when you need strict validation, semantic models, diagnostics, rendering, navigation, or safe refactoring. A recovered Tree-sitter tree is useful editor state; it is not proof that Mermaid will accept or render the document.

Packages

| Consumer | Package or artifact | Provides | | --- | --- | --- | | Node.js | @mermanjs/tree-sitter-mermaid | Native Node binding, TypeScript declarations, queries, and language WASM | | Browser or Worker | @mermanjs/tree-sitter-mermaid + web-tree-sitter | Language WASM and portable queries for the generic browser runtime | | Rust | tree-sitter-mermaid | LANGUAGE, NODE_TYPES, and the portable queries | | C/C++ and editors | Repository source, or a matching GitHub Release | Generated C parser/scanner, public header, Make, CMake, and pkg-config metadata |

The grammar has its own version line, independent of Merman. Its npm and Cargo artifacts share that grammar version, but their registry names differ: the npm package is scoped under @mermanjs, while the Rust crate and C library retain the standard tree-sitter-mermaid name.

This guide targets the 0.3.2 candidate. Relative to published 0.3.1, this patch raises the Rust cc build-dependency minimum from 1.8.0 to 1.10.0 and maintains workspace conformance tests. Accepted syntax, queries, Mermaid/ZenUML baselines, language ABI 15, and runtime versions remain unchanged. Candidate packages become available only after the release preparation record confirms their release. Match the examples to the version installed in your project; earlier versions have their own tagged documentation. Custom query consumers should review the migration guide.

Node.js

npm install [email protected] @mermanjs/[email protected]

With npm 12 or later, review and approve the native install scripts, then rebuild:

npm install-scripts approve tree-sitter @mermanjs/tree-sitter-mermaid
npm rebuild tree-sitter @mermanjs/tree-sitter-mermaid

Commit the resulting allowScripts entries in your application's package.json so subsequent installs use the same version-specific approvals. Browser-only consumers do not need native scripts.

const Parser = require('tree-sitter');
const Mermaid = require('@mermanjs/tree-sitter-mermaid');

const parser = new Parser();
parser.setLanguage(Mermaid);

const tree = parser.parse('flowchart TD\nA --> B\n');
console.log(tree.rootNode.toString());

The tree-sitter peer dependency is optional so a browser-only install does not pull in the native Node runtime. Node applications should use the native binding rather than the browser WASM.

Node ESM consumers use default imports for the CommonJS native bindings:

import Parser from 'tree-sitter';
import Mermaid from '@mermanjs/tree-sitter-mermaid';

Browser and Workers

npm install [email protected] @mermanjs/[email protected]

The package exports @mermanjs/tree-sitter-mermaid/tree-sitter-mermaid.wasm. Copy that asset to a public URL with your bundler, then load it with the generic web-tree-sitter runtime:

import { Language, Parser } from 'web-tree-sitter';

await Parser.init();
const language = await Language.load('/assets/tree-sitter-mermaid.wasm');

const parser = new Parser();
parser.setLanguage(language);
const tree = parser.parse('sequenceDiagram\nAlice->>Bob: Hello\n');

A no-build browser prototype can pin the exact grammar version on jsDelivr:

const language = await Language.load(
  'https://cdn.jsdelivr.net/npm/@mermanjs/[email protected]/tree-sitter-mermaid.wasm',
);

The grammar package deliberately does not wrap runtime initialization, Worker lifecycle, or bundler URL resolution in another JavaScript SDK. Merman's Playground follows the same boundary: a syntax Worker runs this WASM and the portable highlight query, while a separate semantic Worker owns diagnostics, completion, navigation, and rename.

Rust

cargo add tree-sitter@=0.27.1 tree-sitter-mermaid@=0.3.2

let language: tree_sitter::Language = tree_sitter_mermaid::LANGUAGE.into();
let mut parser = tree_sitter::Parser::new();
parser.set_language(&language)?;

let tree = parser
    .parse("flowchart TD\nA --> B\n", None)
    .expect("Tree-sitter returned no tree");
assert!(!tree.root_node().has_error());
# Ok::<(), Box<dyn std::error::Error>>(())

The crate exports a tree-sitter-language::LanguageFn and does not force a Tree-sitter runtime version on applications.

C and C++

The committed parser and scanner build without the grammar generator:

cmake -S . -B build -DBUILD_SHARED_LIBS=OFF
cmake --build build
cmake --install build --prefix /usr/local

Unix-like consumers may alternatively use make and make install.

#include <tree_sitter/api.h>
#include <tree_sitter/tree-sitter-mermaid.h>

int main(void) {
  TSParser *parser = ts_parser_new();
  ts_parser_set_language(parser, tree_sitter_mermaid());
  ts_parser_delete(parser);
  return 0;
}

Version 0.3.2 pairs with Tree-sitter CLI, Rust, and Web runtime 0.27.1; the Rust language adapter uses compatible ^0.1.9, and the generated language ABI remains 15. See query migration when upgrading queries and the grammar release guide when maintaining the package.

Compatibility

| Contract | Version | | --- | --- | | Original 35-family Mermaid syntax baseline | 11.16.1 | | Agentflow and Usecase syntax | 12.0.0 | | ZenUML Core syntax baseline | 3.50.1 | | Tree-sitter language ABI | 15 | | Generator CLI | 0.27.1 | | Rust language crate requirement / audited version | ^0.1.9 / 0.1.9 | | Tested Rust runtime | 0.27.1 | | Tested Web runtime | 0.27.1 | | Native Node runtime contract | 0.25.x |

Before 1.0, a minor release may change named nodes, fields, canonical captures, the language ABI, or the selected Mermaid baseline. Pin a compatible minor version for application integrations and an immutable release commit for editor integrations.

Queries and Editors

tree-sitter.json selects the canonical portable queries under queries/portable/:

• highlights.scm for base syntax highlighting;
• injections.scm for embedded languages;
• locals.scm for syntax-local scopes; and
• tags.scm for syntax-level symbols.

The queries/neovim, queries/helix, and queries/zed directories are pre-1.0 adoption assets. Those editors own their final query copies and release cadence, so publishing this package does not update an editor automatically. Downstream integrations should pin a released Merman commit and use distribution/tree-sitter-mermaid as the grammar subdirectory.

Development

From the Merman repository root, install the pinned package-local toolchain:

npm ci --ignore-scripts --prefix distribution/tree-sitter-mermaid
npm rebuild tree-sitter-cli --prefix distribution/tree-sitter-mermaid

The package manifest approves only the pinned Tree-sitter CLI and native runtime install scripts. --ignore-scripts still suppresses them during the initial install; the explicit rebuild downloads the CLI executable.

Run the ordinary grammar and binding checks:

npm run check:generated --prefix distribution/tree-sitter-mermaid
npm run test:corpus --prefix distribution/tree-sitter-mermaid
cargo nextest run --locked -p tree-sitter-mermaid --no-fail-fast
npm run test:node --prefix distribution/tree-sitter-mermaid
npm run test:c --prefix distribution/tree-sitter-mermaid

Language-WASM freshness and execution are separate, slower checks:

npm run check:wasm --prefix distribution/tree-sitter-mermaid
npm run test:wasm --prefix distribution/tree-sitter-mermaid

Regenerate both parser sources and language WASM after changing the version in tree-sitter.json: the pinned generator embeds that version in TSLanguage.metadata.

metadata/provenance.json pins the WASI SDK 34 release and its LLVM commit. The official Windows compiler reports 23.1.0-rc3; Linux and macOS report 23.1.0-wasi-sdk because the SDK build configuration overrides LLVM_VERSION_SUFFIX only outside Windows. Generation verifies the SDK's VERSION and the exact host-specific compiler banner, including the LLVM commit. -fno-ident prevents that banner from entering the WASM producers section; --no-wasm-opt excludes unpinned optimizers. Freshness checks compare complete source and WASM bytes without normalization or host-specific artifact hashes.

See the development guide and release guide for grammar ownership, generation, testing, and publication details.

License and Provenance

The package is MIT licensed. Source-derived syntax and template attributions are recorded in metadata/provenance.json, metadata/derivations.json, THIRD_PARTY_NOTICES.md, and THIRD_PARTY_LICENSES/. The added families have their own pinned source identity; adding them does not relabel the existing family translations as Mermaid 12.0.0.