[docs] chore: Include a mermaid diagram without the code (not an example)

[weedySeaDragon]

Description

We can and should use mermaid diagrams in the documentation -- not as examples, but purely as diagrams.

We need a way to specify that the mermaid mark-up should not be converted to a mermaid example that also shows the code.

Ex: In the contributing documentation, we should show the main steps for contributing code:

graph LR
  %%{init: { "theme": "neutral" } }%%
    git[1. Checkout a git branch] --> codeTest[2. write tests and code] --> doc[3. update documentation] --> submit[4.submit a PR]
    classDef default fill:white;

Loading

This should just be a diagram; we don't want to show the underlying mermaid code.

What is the code tag we want to use?

I'd prefer that anything that is explicitly meant to be an example be tagged with mermaid-example and everything that is just to be rendered as a diagram be tagged with mermaid. This keeps the documentation standardized in line with what is done everywhere else.

I know there was some discussion of this before but I don't recall the nuances that went into it. (It was just as I started contributing, I think.)

Steps to reproduce

Create a mermaid diagram in a documentation file (.md).
Run docs:dev to see it on a local server.

Observe that the source for the diagram is always extracted as code.

Screenshots

No response

Code Sample

No response

Setup

No response

Additional Context

No response

[flywire]

Mermaid usage sucks on GitHub. Unlike every other language, a code block is executed rather than displayed. A prefix on the first line like ! should have been used for execute.

---

#3927 comment - use backticks without mermaid which renders without syntax highlighting

[apeacock1991]

Is there a reason not to just use backticks without specifying Mermaid? That would then not render on GitHub, for example, and show you the diagram's markup.

[weedySeaDragon]

@flywire - what you are asking about is the opposite of what I need.

I need the diagram to be rendered, but do not want the code to be shown.
And specifically, I want this for the mermaid documentation. Currently the mermaid documentation process includes a pre-processing step that that copies the mermaid diagram text so that it can be displayed.

[sidharthv96]

@weedySeaDragon the only reason I can recall for converting mermaid, mermaid-example and mmd were

• Existing docs were inconsistent, so we just rendered code with everything instead of checking each individual diagram.
• Something to do with existing implementation in github, gitlab and all. I can't recall what exactly it was.

We can just edit this check to just split mermaid-example.

mermaid/packages/mermaid/src/docs.mts

Lines 191 to 192 in cdba2b4

	if (['mermaid', 'mmd', 'mermaid-example'].includes(c.lang)) {
	c.lang = 'mermaid-example';

But, we also need to update contribution guidelines and review each PRs thoroughly to verify that people don't simply add mermaid blocks in example, as that's what they use everywhere else. Then we will end up in the old situation where few diagrams had code blocks and few didn't.

Another option is to add a new tag we could use only in our documentation to skip code splitting.
mermaid-nocode/mermaid-diagram/mermaid!/!mermaid

[weedySeaDragon]

Definitely don't want to end up in that old situation where some mermaid blocks have code examples and some don't.
Also don't want to add work for reviewing PRs.

So it seems like adding a new, explicit tag to use only in the documentation would be the way to do. I think that something that is not like the default mermaid tag would be best so that someone doesn't accidentally use it. So I'd vote for

mermaid-nocode