Weekly GitHub Report for Mermaid

Thank you for subscribing to our weekly newsletter! Each week, we deliver a comprehensive summary of your GitHub project's latest activity right to your inbox, including an overview of your project's issues, pull requests, contributors, and commit activity.

Table of Contents

• I. News
  • 1.1. Recent Version Releases
  • 1.2. Other Noteworthy Updates
• II. Issues
  • 2.1. Top 5 Active Issues
  • 2.2. Top 5 Stale Issues
  • 2.3. Open Issues
  • 2.4. Closed Issues
  • 2.5. Issue Discussion Insights

• III. Pull Requests
  • 3.1. Open Pull Requests
  • 3.2. Closed Pull Requests
  • 3.3. Pull Request Discussion Insights

• IV. Contributors
  • 4.1. Contributors

I. News

1.1 Recent Version Releases:

The current version of this repository is @mermaid-js/[email protected]

1.2 Version Information:

On March 25, 2025, a minor update was released introducing a new Radar Chart feature, enhancing the charting capabilities of the platform. This addition reflects ongoing efforts to expand visualization options.

II. Issues

2.1 Top 5 Active Issues:

We consider active issues to be issues that that have been commented on most frequently within the last week. Bot comments are omitted.

1. [TYPE: ENHANCEMENT] [CONTRIBUTOR NEEDED] [STATUS: APPROVED] [GOOD FIRST ISSUE!] [GRAPH: ENTITY RELATIONSHIP] multiple word type in erDiagram attributes: This issue addresses the limitation in the erDiagram syntax where attribute types and names must be single words, which prevents the use of multi-word types like Id Person or complex types such as integer ARRAY. The user requests a way to declare multi-word types, possibly by using quotes or other delimiters, to better support high-level type definitions like those found in Haskell or PostgreSQL.

   • The comments discuss potential workarounds such as using underscores or enclosing multi-word types in quotes, with a later update noting that wrapping attribute names and types in backticks now allows multi-word and special-character types to be parsed correctly, suggesting the issue may be resolved.
   • Number of comments this week: 1

2. [TYPE: BUG / ERROR] [GOOD FIRST ISSUE!] [STATUS: TRIAGE] [FOSSHACK] Starting task after milestone doesn't work with >1 milestone: This issue describes a problem where starting tasks after multiple milestones in a Gantt chart does not work correctly due to syntax and parsing errors related to how milestones are defined. The reporter demonstrates that tasks starting after one milestone behave as expected, but when involving more than one milestone, the tasks do not start at the correct times, and the root cause appears to be the milestone syntax requiring a duration field to be properly recognized.

   • The comments clarify that the issue stems from incorrect milestone syntax where the milestone ID and duration are misplaced, causing the parser to fail or fallback incorrectly; a workaround involves explicitly specifying a zero duration for milestones, and a related fix has been proposed to handle these cases more gracefully in the parser.
   • Number of comments this week: 1

3. [TYPE: BUG / ERROR] Direction in subgraphs inconsistent: This issue reports inconsistent behavior in the directional layout of nested subgraphs within Mermaid flowcharts, where specified directions such as left-to-right or top-to-bottom are not consistently applied across different levels of nested objects. The user provides detailed examples and code snippets demonstrating that despite setting explicit directions, the rendered diagrams do not follow these instructions, suggesting a bug in how Mermaid handles direction inheritance and rendering in complex nested subgraphs.

   • The comments discuss similar experiences with direction inconsistencies, reference known limitations in Mermaid's handling of subgraph directions, and share examples illustrating the problem; contributors acknowledge the issue has persisted for years, identify a root cause related to the Dagre layout engine's cluster object not fully supporting direction attributes, and link to related pull requests aiming to fix the problem.
   • Number of comments this week: 1

4. [TYPE: ENHANCEMENT] [CONTRIBUTOR NEEDED] [STATUS: APPROVED] [GRAPH: FLOW] Allow linkStyle based on link text: This issue proposes enhancing the Mermaid diagram tool by allowing the linkStyle attribute to be applied based on link text rather than just link number, which currently makes styling fragile and difficult to maintain in complex flowcharts. The suggestion includes maintaining precedence for numeric link styles and keeping a default style for unspecified links, aiming to simplify updates and improve usability for diagrams with many binary decision links.

   • The comments acknowledge the niche nature of the issue and confirm it does not conflict with related issues, express agreement on the current limitations of numeric link styling, explain the technical changes needed for implementation, and highlight the importance of this feature for accessibility compliance.
   • Number of comments this week: 1

5. [TYPE: QUESTION] [STATUS: DISCUSSION NEEDED] Feature Request: Allow subgraphs to have different directions than the main graph (e.g., LR inside TD): This issue requests the ability for subgraphs in Mermaid diagrams to have independent directional flows (such as left-to-right inside a top-down main graph), which is currently unsupported and limits diagram flexibility. The discussion reveals that while the feature partially exists in the flowchart syntax, it behaves inconsistently due to how edges connecting internal subgraph nodes to external nodes affect layout direction, leading to confusion over whether this is a bug or a feature limitation.

   • Commenters agree this is a longstanding problem with inconsistent behavior depending on edge routing; it is clarified that subgraph direction works if external edges connect to the subgraph as a whole rather than its internal nodes, but this workaround is not always practical, and the issue remains unresolved after years of discussion.
   • Number of comments this week: 1

2.2 Top 5 Stale Issues:

We consider stale issues to be issues that has had no activity within the last 30 days. The team should work together to get these issues resolved and closed as soon as possible.

As of our latest update, there are no stale issues for the project this week.

2.3 Open Issues

This section lists, groups, and then summarizes issues that were created within the last week in the repository.

Issues Opened This Week: 9

Summarized Issues:

• Event Modeling Diagram Bugs: Multiple issues highlight problems in the event modeling diagram, including non-unique frame IDs causing incorrect relation links and ignored explicit source relations on reset frames, leading to misleading or missing connections. Proposed improvements include making frame IDs optional, changing operator directions, and enhancing frame referencing to reduce errors and complexity.
• issues/8287, issues/8288, issues/8290

• Layout and Labeling Issues in Diagrams: Several issues report layout problems such as misaligned edge labels in ELK layouts, overlapping cardinality labels in class diagrams, and node displacement when adding labels between nodes in swimlanes, all affecting readability and diagram accuracy. These problems call for better label placement algorithms and swimlane rework to maintain node alignment regardless of label or edge changes.
• issues/8292, issues/8327, issues/8335

• Rendering and Sizing Problems: There is a bug where CSS transitions on <foreignObject> elements cause Mermaid to compute an excessively large SVG viewBox, resulting in incorrect diagram sizing and excessive empty space. This issue affects the visual correctness of rendered diagrams under certain styling conditions.
• issues/8308

• Documentation and Usability Requests: A request was made to include version availability information for each diagram type in the Mermaid documentation to assist users relying on older versions, such as those used by GitHub. This would improve user awareness of feature support across versions.
• issues/8289

• Text Display Limitations: Users experience difficulty displaying multi-line titles in the Mermaid live editor and Visual Studio Code, indicating limitations in text formatting support within these environments. This affects the ability to present titles clearly in diagrams.
• issues/8319

2.4 Closed Issues

This section lists, groups, and then summarizes issues that were closed within the last week in the repository. This section also links the associated pull requests if applicable.

Issues Closed This Week: 11

Summarized Issues:

• Layout and Spacing Issues in Diagrams: Several issues highlight problems with layout and spacing in Mermaid diagrams, including incorrect application of nodeSpacing and rankSpacing in state diagrams, inability to configure spacing and feedback-edge routing in the ELK layout causing excessive empty space and inefficient edge routing, and flowcharts with repeated subgraph IDs rendering with NaN geometry in the ELK layout. These problems result in rendering errors, inefficient layouts, and console errors, particularly affecting subgraphs and nested elements.
• issues/2263, issues/8302, issues/8326

• Dependency and Security Vulnerabilities: Multiple issues report that Mermaid depends on outdated versions of dependencies such as chevrotain and lodash-es, which include known security vulnerabilities and cause duplicate code in bundles. Upgrading to newer versions of these dependencies is suggested to remove vulnerabilities, reduce bundle size, and maintain compatibility with required Node.js versions.
• issues/8278, issues/8332

• Diagram Rendering and Element Positioning Bugs: There are issues with rendering and positioning in various diagram types, including SVG output errors in C4 diagrams due to missing namespace declarations, clipping and misplacement of relation cardinality labels in class diagrams using ELK layout, and misaligned chart titles in xyChart diagrams caused by incorrect centering over the full SVG width instead of the plot area. These bugs affect the clarity and correctness of diagram visuals.
• issues/4092, issues/8329, issues/8336

• Theme and Styling Configuration Problems: One issue describes how partially overriding nested theme variable objects like xyChart results in the entire object being replaced rather than merged, causing loss of the active theme's color palette and fallback to default colors. This affects the rendering consistency of charts and diagrams that rely on nested theme configurations.
• issues/8299

• Parsing and Keyword Conflicts: An issue reports that declaring a participant with the ID "Link" in sequence diagrams causes message references to fail because "link" is treated as a reserved keyword, leading to parse errors despite correct participant declaration. This keyword conflict disrupts normal diagram parsing and rendering.
• issues/8280

• Feature Enhancement for Version Comparison: A proposed feature suggests adding a "Compare" tab to the dev server to enable side-by-side rendering comparisons of Mermaid diagrams across different published versions and the current dev build. This feature would include independent version selectors, visual diff overlays, URL state persistence, isolated rendering environments, and graceful error handling to improve development and testing workflows.
• issues/8328

2.5 Issue Discussion Insights

This section will analyze the tone and sentiment of discussions within this project's open and closed issues that occurred within the past week. It aims to identify potentially heated exchanges and to maintain a constructive project environment.

Based on our analysis, there are no instances of toxic discussions in the project's open or closed issues from the past week.

III. Pull Requests

3.1 Open Pull Requests

This section provides a summary of pull requests that were opened in the repository over the past week. The top three pull requests with the highest number of commits are highlighted as 'key' pull requests. Other pull requests are grouped based on similar characteristics for easier analysis. Up to 25 pull requests are displayed in this section, while any remaining pull requests beyond this limit are omitted for brevity.

Pull Requests Opened This Week: 27

Key Open Pull Requests

1. feat: add grid layout algorithm: This pull request introduces a comprehensive built-in grid layout algorithm for Mermaid diagrams, enabling logical row and column placement of nodes and groups across multiple diagram types with deterministic coordinate filling, obstacle-aware orthogonal edge routing, configurable edge curves, shape-aware endpoints, extensive documentation, a development demo, and broad testing coverage to enhance layout precision, routing performance, and user configurability.

• URL: pull/8293

• Associated Commits: 0c0e7, d7d83, 7f837, 57cb5, b01c8, fcaa6, 5c798, 8bd2e, 8c361, f7d25, 3453a, 73b8e, 66d63, b123e, a4d8d, 86247, f4779, 067da, 4d73d, 03a92, 0282f, 0bb27, 4abef, c719b, 1d7a3, 7d48c, 2af79, 02baf, 52609, d708c, f1e7a, d4b2b, de20d, 3dd31, 20aba, 488e1, 7de16, 9228f, b4605, a1720, ffd63, e6cb9, ca778, 1ddd8, 2dd8f, bdf62, e1c6d, 5c7e9, 4ebc2, a7736, e6348, 56c15, a74d0, 9d81a

2. fix: preserve encoded newlines/carriage returns in link URLs: This pull request fixes an issue where encoded newlines (%0A) and carriage returns (%0D) in link URLs' query strings or fragments were being stripped away by the sanitizeUrl function at security levels other than loose by introducing a mechanism that temporarily shields these sequences with unique placeholder tokens before sanitization and restores them afterward, thereby preserving intended line breaks in URLs without compromising existing protocol-based security checks.

• URL: pull/8306

• Associated Commits: 57235, 5649a, 4d732, cf9ed, 66268, 92a1b, d3625, 43c9c, cbeec, 15128, 3512a, 1c5e4, f42b0, 38a5b, ebbdb, fea5d, d16f7, de903, f04eb, 99cfa, 388b1, e6e2e, 06e73, 466b9, 690ab, 89cc7, d4a11, d3620, 5b7c8, c0e85, de245, 357af, 98200, 6ec56, 60e84

3. fix(flowchart, stateDiagram): render every self-loop on a node instead of only the last one: This pull request fixes an issue in Mermaid's flowchart and state diagram rendering where multiple self-loops on a single node were incorrectly merged and only the last loop was displayed by updating the dummy node and edge IDs to be unique per edge and stacking overlapping loops outward to prevent visual overlap, accompanied by new tests verifying the correct rendering of all self-loops.

• URL: pull/8286

• Associated Commits: d747f, 94ea0, 3f5f7, c3cc0, 53c07, c4251, b7c1c, e538b, cf834, 784ae, 386bb, 139f4, 7abfe, 69778, bdee5

Other Open Pull Requests

• BPMN Diagram Feature: This pull request introduces a native AI-first BPMN diagram feature to Mermaid supporting BPMN 2.0 Level 1 descriptive conformance with intermediate events, a tolerant and self-correcting DSL parser, deterministic rendering, and a one-way BPMN 2.0 XML export validated for compatibility with bpmn.io. It aims to advance the BPMN integration discussion while complementing existing efforts.
  • pull/8313

• C4-beta Diagram Enhancements: These pull requests add new configuration options to the c4-beta diagram type, including showStereotypes, hideStereotypes, and personWrappingWidth to control stereotype visibility and label wrapping, enhancing customization for diagram rendering. Additionally, support for an undirected relationship syntax --- is introduced, drawn without arrowheads, though its use is discouraged due to lack of Structurizr equivalence.
  • pull/8324, pull/8323

• Threat Modeling Annotations: This pull request introduces an experimental proof-of-concept feature adding versioned YAML frontmatter annotations for threat modeling to Mermaid flowcharts. It enables inclusion, validation, and rendering of detailed security metadata such as components, threats, risk scores, and mitigations directly within flowchart files without altering the core diagram grammar.
  • pull/8318

• Radar Diagram Range Support: This pull request adds support for range-valued entries in radar diagrams using a new [start..end] syntax for intervals on each axis, compatible with positional and named entries. It preserves existing literal rendering, reuses the current scaling system, implements independent smoothing for graticules, and includes documentation, examples, and tests.
  • pull/8301

• Event-Modeling Fixes: These pull requests fix the event-modeling feature by rejecting duplicate time and reset frame IDs before rendering, reporting duplicates with source line numbers, clearing stale diagrams on parse failure, preserving comments for diagnostics, and preserving explicit ->> source relations while suppressing inferred ones. They include regression tests and documentation updates clarifying uniqueness requirements and syntax examples.
  • pull/8297, pull/8296

• Mermaid Online and FlowViz Editors: These pull requests add Mermaid Online and FlowViz, two browser-based Mermaid editors with live preview, multiple export options, themed styles, AI-assisted features, and compatibility with mermaid.live share links, to the community integrations list under Productivity tools in the project documentation.
  • pull/8311, pull/8314

• ELK Layout Improvements: This pull request introduces two new optional configuration settings, elk.wrappingStrategy and elk.aspectRatio, to the ELK layout in Mermaid, enabling long chains to fold into rows based on a specified width-to-height ratio. Another pull request adds a new ELK rendering pass that slides cardinality labels on class diagram edges crossing namespace frames to maintain minimum clearance, improving label placement without breaking existing functionality.
  • pull/8321, pull/8339

• Gantt Chart Parsing Fixes: These pull requests fix Gantt chart parsing by allowing milestones to be declared without duration, treating entries with an ID and start date as zero-duration milestones, and correctly handling integer start dates in dateFormat X as Unix seconds. They preserve existing parsing behavior for tasks with durations and update documentation and tests accordingly.
  • pull/8291, pull/8312

• Flowchart and Timeline Parser Fixes: These pull requests improve flowchart documentation by clarifying Unicode text and emoji usage in node labels and fix the timeline parser to allow colons within time periods when not followed by whitespace, ensuring existing event separators continue to function. They include updated tests, documentation, and changesets.
  • pull/8304, pull/8309

• Accessibility Attributes in Block Diagrams: This pull request fixes the block lexer and grammar by adding support for accessibility attributes accTitle and accDescr in block diagrams, exposing their getters and setters on the block database, and including parser tests to ensure proper handling.
  • pull/8310

• Mermaid Diagrams for Confluence: This pull request adds a new entry for "Mermaid Diagrams & Gantt for Confluence," a Forge macro that renders Mermaid diagrams in Confluence Cloud pages, to the Community integrations section under Productivity tools for Atlassian Products in the documentation.
  • pull/8315

• Pie Chart Theme Variable Documentation: This pull request adds documentation for the pieOuterStrokeWidth theme variable, clarifying its role as the outer circle border width, CSS length format, default value of "2px", and distinction from pie configuration parameters by placing it under themeVariables.
  • pull/8316

• Syntax Metadata Package: This pull request introduces an experimental @mermaid-js/syntax-metadata package that extracts and consolidates diagram syntax data from Mermaid's grammars to provide editor-ready language metadata. This enables tools like IDE extensions and language servers to avoid re-implementing keywords, operators, snippets, and identifier extraction.
  • pull/8294

• Sankey Diagram Unicode Support: This pull request fixes the Sankey diagram parser to allow non-ASCII characters—including CJK, accented Latin, Cyrillic, and emoji—in both quoted and unquoted labels by extending the TEXTDATA character class to cover Unicode code points up to U+FFFF while preserving CSV parsing semantics. It includes regression tests to verify the fix.
  • pull/8295

• ER Diagram Documentation and Regression Test: These pull requests update the ER diagram documentation to explicitly include commas and periods as valid characters in attribute types, clarifying support for SQL-style types without code changes. Another adds the ER diagram from issue #6047 as an end-to-end regression test fixture to prevent renderer freezes in affected Mermaid versions.
  • pull/8305, pull/8307

• CSS Transition Fix for ViewBox: This pull request fixes an issue where host page CSS transitions caused <foreignObject> elements in Mermaid diagrams to temporarily retain large measurement sizes, inflating the diagram's viewBox. It disables transitions on these elements through inline styles and shared CSS to ensure accurate viewBox dimensions.
  • pull/8320

• Person Shape Proportions Fix: This pull request fixes the person shape in diagrams by setting a minimum body height relative to width, increasing the head radius cap, centering the label between head and body bottom, defining sizing ratios as named constants, and adding tests to verify these geometric adjustments.
  • pull/8322

3.2 Closed Pull Requests

This section provides a summary of pull requests that were closed in the repository over the past week. The top three pull requests with the highest number of commits are highlighted as 'key' pull requests. Other pull requests are grouped based on similar characteristics for easier analysis. Up to 25 pull requests are displayed in this section, while any remaining pull requests beyond this limit are omitted for brevity.

Pull Requests Closed This Week: 9

Key Closed Pull Requests

1. fix(class): place cardinality labels beside their ends with the ELK layout: This pull request fixes the placement and rendering of cardinality labels in class diagrams using the ELK layout by measuring and passing label sizes to ELK for proper spacing, ensuring labels are positioned beside their relation ends without clipping or overlap, mirroring labels onto appropriate sides when space allows, centering end labels consistently with start labels, and applying sizing improvements that also benefit dagre layouts, all verified through extensive unit and end-to-end tests.

• URL: pull/8334

• Associated Commits: d6733, 2c1db, 96a70, 5eec9, 060ba, b3dee, 8f386, 776e6

2. fix(elk): route an edge back into a subgraph downstream, not around it: This pull request fixes the ELK layout by detecting edges that feed back into a subgraph and routing them downstream inside the subgraph rather than around its outside, introducing a new elk.orientFeedbackEdges option enabled by default to reverse such edges before layout and restore their direction afterward, thereby reducing edge length and improving diagram clarity while preserving existing cycle-breaking strategies for other cases.

• URL: pull/8303

• Associated Commits: 91407, ac109, 8d0f7, 2a9fa, 7f41b

3. fix(sequence): Update Actor definition with config to match other actor definitions: This pull request aims to fix the sequence diagram parser by updating the Actor definition's regular expression to consistently handle actors followed by configuration objects, ensuring naming rules align with other actor definitions and improving test coverage without altering public APIs.

• URL: pull/8086

• Associated Commits: 9ade4, d6109, c8c72

Other Closed Pull Requests

• Sequence Diagram Parser and Lexer Fixes: These pull requests address issues in the sequence diagram parser and lexer to allow participant IDs named Link, link, or LINK without misinterpretation as keywords or commands. They ensure case-insensitive acceptance while preserving original spelling and improve handling of actor references in messages with added regression tests and validation.
• pull/8282, pull/8285

• Dependency Upgrades and Parser Improvements: These pull requests upgrade key dependencies such as chevrotain and Langium to newer versions, removing vulnerable and legacy packages like lodash-es 4.17.23. They also enhance parser error reporting, handle token location issues, and ensure compatibility with Node.js requirements without breaking changes.
• pull/8330, pull/8333

• Chart Title Alignment Fix: This pull request fixes the xychart title alignment by centering it over the plot area instead of the full SVG width, introducing a new ChartTitle.alignTo(start, end) method. It updates the orchestrator to position the title based on the plot's horizontal extent and adds unit and end-to-end tests to verify correct alignment in various chart configurations.
• pull/8338

• Theme Variable Merge Strategy Fix: This pull request resolves the issue of losing generated keys when partially overriding nested object-valued theme variables by implementing a merge strategy that preserves existing keys while applying user overrides. This ensures consistent and correct theming behavior across all themes without changing documented usage.
• pull/8300

3.3 Pull Request Discussion Insights

This section will analyze the tone and sentiment of discussions within this project's open and closed pull requests that occurred within the past week. It aims to identify potentially heated exchanges and to maintain a constructive project environment.

Based on our analysis, there are no instances of toxic discussions in the project's open or closed pull requests from the past week.

IV. Contributors

4.1 Contributors

Active Contributors:

We consider an active contributor in this project to be any contributor who has made at least 1 commit, opened at least 1 issue, created at least 1 pull request, or made more than 2 comments in the last month.

If there are more than 10 active contributors, the list is truncated to the top 10 based on contribution metrics for better clarity.