wip: Add optInMarkdownLabels config setting

[ajuckel]

📑 Summary

This is a quick strawman implementation of the direction I'm proposing to resolve #6275.

Resolves #6275

Examples of types of labels causing issues in an external project:

After applying new config setting with these changes:

📏 Design Decisions

I've added an optInMarkdownLabels config setting. It defaults to false, but when enabled (either in frontmatter, or in a call to initialize), it turns off the auto-markdown processing for node labels.

The primary goal is to provide a less intrusive upgrade path from Mermaid 10 to 11. Users who encounter markdown issues in their node rendering when upgrading to Mermaid 11 could set optInMarkdownLabels to false in order restore a closer approximation of the 10.x behavior. I'm not claiming this PR will ever guarantee no rendering changes in the upgrade from 10 to 11, but it will certainly provide a fix for the Unsupported markdown issues that can be accidentally encountered during the upgrade.

There are many issues to solve before the implementation could be considered for merge. I'm sharing the early draft just as a conversation point, to see if this approach would be acceptable if the following issues were resolved.

• Need to examine closer whether my new opt-in label maker effectively captures the behavior of the old 10.7 labels. This initial sketch just wraps the text in a span.
• Currently, the expected double-quote-backtick delimiter is being removed before the text is sent to the label node. I haven't found where that's happening.
• I've only defaulted the useHtmlLabels path, which calls markdownToHTML. I should probably update the markdownToLines path for useHtmlLabels=false as well.
• No existing unit tests have been run to verify I haven't broken anything.
• No new unit tests have been written to verify the new behavior.

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2025302

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	2025302
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/67c46b94d3b70200086bab50
😎 Deploy Preview	https://deploy-preview-6277--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[pkg-pr-new]

Open in Stackblitz

npm i https://pkg.pr.new/mermaid-js/mermaid@6277

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/mermaid-zenuml@6277

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/layout-elk@6277

npm i https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/parser@6277

commit: 2025302

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 36 lines in your changes missing coverage. Please review.

Project coverage is 3.88%. Comparing base (bc2bd3d) to head (2025302).

Files with missing lines	Patch %	Lines
packages/mermaid/src/rendering-util/createText.ts	0.00%	22 Missing ⚠️
...c/rendering-util/rendering-elements/shapes/util.ts	0.00%	13 Missing ⚠️
packages/mermaid/src/diagrams/flowchart/flowDb.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #6277      +/-   ##
==========================================
- Coverage     3.88%   3.88%   -0.01%     
==========================================
  Files          398     399       +1     
  Lines        42044   42081      +37     
  Branches       638     638              
==========================================
  Hits          1635    1635              
- Misses       40409   40446      +37     

Flag	Coverage Δ
unit	3.88% <0.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/config.type.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/flowchart/flowDb.ts	0.00% <0.00%> (ø)
...c/rendering-util/rendering-elements/shapes/util.ts	0.00% <0.00%> (ø)
packages/mermaid/src/rendering-util/createText.ts	0.45% <0.00%> (-0.05%)	⬇️

... and 1 file with indirect coverage changes

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Mar 2, 2025, 2:40 PM

[ajuckel]

I spent some more time looking through the project today. Looking through the e2e tests, unless I missed something, it seems the only time markdown rendering is tested is when it is within the double-quote-backtick delimiters. Also, I see other issues/PRs addressing the same, or at least highly similar, issue.

For example: #5824 and associated PR #6087. Both this PR and that apply the change to pull the vertex labelType into the node (though they also do the same for the edges, which I had not yet done).

Looking at the comments there, that PR seems idle for 3 months. My attempt here has had no maintainer feedback for 2 weeks. I'd be willing to either apply my config setting approach in this PR to theirs, or adopt their re-use of createLabel here in this PR. Or even just test their PR more completely for my cases, to see if my needs are satisfied simply by adopting their work. My concern is less with how exactly the (AFAICT unintentional) backwards compatibility regression is fixed, or at least fixable with a global config setting. I'm more concerned with simply enabling some path toward 11.x adoption that doesn't require editing dozens of diagrams individually.

[ajuckel]

I'm inclined to withdraw this PR in favor of #6345. It seems a change without additional configuration, simply restoring the old behavior, was very close to merging recently. That PR wasn't quite sufficient for my needs, so I added some small changes in #6345.

If the maintainers would prefer a configuration option, I can add that in #6345.