GitLab Docs Mermaid Rendering Test

Note: I've updated the diagram source to be the diagrams I have updated in !197387 to provide backwards compatibility. That means there should no longer be any rendering errors with either Mermaid 10 or 11.

All Diagrams (Mermaid 10.7): Test page with all diagrams from the docs directory. Generated with a very trivial shell script, so some rendering errors may be due to simple script errors. Minimal context, each section of diagrams begins with a heading indicating the source for the following diagrams.
All Diagrams (Mermaid 11.11.0): Same as above, but using Mermaid 11.11.0 for rendering.
Comparison Page: Allows you to select a diagram, and view it rendered in both mermaid versions, as well as edit the diagram text.
Proposed Changes: Allows you to view proposed changes to diagrams, and see how they render in both mermaid versions. I've also used jsdiff (and shamelessly copied from its demo page) to render the differences between the proposed and original diagrams.

Backwards Compatibility Issues

Upgrading from Mermaid 10 to Mermaid 11 results in several rendering errors due to upstream changes. I consider these to all be backwards compatibility bugs, and would hope that the Mermaid team would consider engaging with me on my PRs to provide fixes for them. There are two general categories of errors I've identified.

The first is rather trivial, and only affects sequence diagrams. When adding support for bidirectional arrows, the regular expression accidentally disallowed '=' characters to be used in labels. I have submitted PR #6332 to fix this error upstream. To my mind, merging this PR should cause little disruption.

The second issue is more far-reaching and therefore more difficult to resolve. The parsers for several diagrams differentiate between plain text and markdown text. The documentation for flowchart diagrams indicates that users should use "`text`" to indicate that a label should be rendered as markdown. In mermaid 10.x, only labels that were explicitly marked as markdown would be rendered as such. In mermaid 11.x, all labels are rendered as markdown, regardless of whether or not they use the doube-quote-backtick syntax to opt-in. This causes issues in several labels in the GitLab documentation, which were never intended to be rendered as markdown and include character sequences that the markdown formatter does not properly handle. Fixing this issue is more difficult. Mermaid is now (at time of writing) on version 11.8.1, this new always-on markdown behavior has had time to establish itself as the new default. Users who have transitioned to 11.x may have come to rely upon this markdown-by-default behavior. I have submitted two separate PRs. My first attempt added a new configuration setting, optInMarkdownLabels. While working on that PR, I found PR #6087, which appeared from my outsider perspective to be very nearly accepted. That PR did not add a new configuration setting, it simply restored the 10.x behavior. This would restore 10.x backwards compatibility, but would break backwards compatibility within the 11.x series. Therefore, I submitted a new PR (#6345) based upon that approach, which also extended the behavior sufficiently to cover all rendering issues in GitLab documentation. In their test suite, it does introduce rendering differences, but that is to be expected. I'd appreciate engagement from the Mermaid team in trying to find an acceptable state for this fix. Perhaps re-adding the configuration setting from 6277 into the 6345 PR would be an acceptable solution.

Workarounds

If GitLab does not wish to wait for upstream fixes before upgrading to Mermaid 11, diagrams with rendering issues will need to be edited to resolve the rendering issues. User-generated content would also be subject to rendering errors, and users would be responsible for fixing their own diagrams.

The general approach I've found most successful is to replace problematic characters with entity references. In my testing, this has been the most successful approach for editing a diagram so it can render successfully (but not necessarily identically) between both versions. I use the mermaid-implemented character entity reference syntax, #num;, as opposed to direct HTML entity &#num;, to avoid e.g. = being rendered as &= by the mermaid encode/decode.

Proposed Diagram Edits

doc/developmen/ai_features/_index.md Diagram 1 (compare orig): A few uses of backtick to quote things. The usage is a bit odd, as it isn't rendered as monospace even in Mermaid 10. Instead, it's rendered as literal backticks. The markdown rendering in mermaid doesn't support codespans, so these result in Unsupported markdown: codespan. Replaced backticks with #96; to resolve the markdown issue, which results in literal backticks being displayed in markdown 11. Still, the markdown labels result in different rendering with more padding, and line wrapping.
doc/development/product_qualified_lead_guide/_index.md Diagram 1 (compare orig): Sequence diagram, so replaced = with #61; to resolve rendering issues.
doc/development/testing_guide/review_apps.md Diagram 1 (compare orig): Several subgraphs used 1., etc for labels, which the new markdown-by-default rendering interprets as a markdown list, but it refuses to render markdown lists, leaving an Unsupported markdown: list error. Fixed by replacing periods with #46;. Done this way instead of using 1\., because the backslash would be rendered in mermaid 10.x. Also resolved Unsupported markdown: codespan cases by replacing backticks with #96;.
doc/tutorials/make_first_git_commit/_index.md Diagram 2 (compare orig): Resolved Unsupported markdown: list cases, so replaced perods with #46;., and resolved Unsupported markdown: codespan by replacing backticks with #96;.
doc/user/group/subgroups/_index.md Diagram 2 (compare orig): Here we had the simple fix for Unsupported markdown: list using #46;, but there were also cases where the Mermaid 10 version used \n in a non-markdown label to insert linebreaks. These aren't translated in the markdown formatter, but literal newlines are, so I replaced \n with literal newlines plus indentation for formatting. Appears to render acceptably in both Mermaid 10 and 11.

The above were the most obvious rendering errors. The following files all used \n within labels, and were resolved by inserting literal newlines in the labels.