Upstream Mermaid 11 has backwards compatibility issues with Mermaid 10

Overview

As I file this issue, GitLab is deployed with Mermaid 10.7 as its Mermaid rendering engine. The latest upstream is now 11.8.1. Throughout the 11.x releases, upstream Mermaid has been interpreting most (all?) labels as Markdown. This is a change from Mermaid 10.x, where a label needed to be enclosed in double-quote backticks (e.g. "`markdown label`") to be interpreted as Markdown.

There have been several requests to update GitLab's Mermaid implementation to take advantage of other features within the 11.x release series. Before making the upgrade,

I'm filing this as an independent issue, because discussion around this issue has been distributed across several merge requests and issues. This issue is intended as a place to focus on the particulars of the known backwards incompatibility issues. This allows a conversation to focus on the handling of these issues, outside the question of whether/how to handle the 11.x dependency upgrade.

Known Issues and Suggested Workarounds for Diagrams in gitlab-org/gitlab>.

  1. Unsupported markdown: list: Labels that started with a number followed by a period are now interpreted as an attempt to create a Markdown list, which is not handled by the Mermaid Markdown parser. As a workaround that's compatible with both Mermaid 10 and 11, replacing the period with #46; will resolve the rendering issue. Using a backslash to escape the period for the 11.x rendering will result in 10.x rendering the backslash verbatim.
  2. Unsupported markdown: codespan: Labels that include a backtick-quoted word or phrase are interpreted as attempts to render a Markdown codespan, which is not supported by the Mermaid markdown renderer. Replacing the backticks with #96; will result in compatible rendering in both 10.x and 11.x.
  3. Literal \n sequences in labels: In 10.x, where the labels were interpreted as plain text, the \n sequence was interpreted as a line break. In 11.x, this sequence is instead rendered verbatim. Replacing \n with a literal newline results in a newline being inserted in both 10.x and 11.x.
  4. Equals signs in labels for sequence diagrams now results in a parsing error. This is unrelated to the markdown-by-default error, but a separate issue introduced upstream after 10.7. As a workaround, replacing the equals sign with #61; allows the diagram to render in both 10.x and 11.x.

Impact for Other Diagrams

I collected the set of 4 known issues above by examining the diagrams in the gitlab-org/gitlab> project. It's certainly possible that there are diagrams in other places that are affected by these 4 specific issues, or other backwards compatibility issues I have not yet encountered. For diagrams under GitLab's control, I imagine similar simple fixes could be created to make those diagrams compatible with a planned 11.x upgrade. For user-controlled diagrams, it would be up to the users themselves to resolve any rendering issues if GitLab decided to upgrade the embedded implementation.

References

  • I've created a simple page to investigate the known rendering issues at https://ajuckel.gitlab.io/mermaid-test/. The site requires manual updates, but it has been useful to me in at least capturing this current state. Perhaps it will be useful to others.
  • Issue #491514: General Mermaid 11.x upgrade issue.
  • Issue gitlab-org/technical-writing/docs-gitlab-com#192: Similar issue for the docs site.
  • MR !171452: Earlier MR to upgrade to Mermaid 11.4.1, which includes a lot of discussion of the backwards incompatibility issues.
Edited by 🤖 GitLab Bot 🤖