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: bfb46af

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	bfb46af
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/67ae3f8476266a0008e0d55b
😎 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/layout-elk@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/parser@6277

commit: bfb46af

[codecov]

Codecov Report

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

Project coverage is 4.47%. Comparing base (b4879d1) to head (bfb46af).
Report is 127 commits behind head on develop.

Files with missing lines	Patch %	Lines
packages/mermaid/src/rendering-util/createText.ts	0.00%	16 Missing ⚠️
...c/rendering-util/rendering-elements/shapes/util.ts	0.00%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #6277      +/-   ##
==========================================
- Coverage     4.49%   4.47%   -0.03%     
==========================================
  Files          383     385       +2     
  Lines        53925   54208     +283     
  Branches       596     598       +2     
==========================================
  Hits          2425    2425              
- Misses       51500   51783     +283     

Flag	Coverage Δ
unit	4.47% <0.00%> (-0.03%)	⬇️

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

Files with missing lines	Coverage Δ
...c/rendering-util/rendering-elements/shapes/util.ts	0.00% <0.00%> (ø)
packages/mermaid/src/rendering-util/createText.ts	0.00% <0.00%> (ø)

... and 21 files with indirect coverage changes