Mermaid in gitlab issues, comments, and wikis

Using mermaid in gitlab issues means a fenced block in the issue description or in a comment, rendered when GitLab draws that page. The fence works in issues, in merge requests, in the wiki, and in repository Markdown. This page stays on the issue and the comments under it. The broader tour, including the README case, is the Mermaid in GitLab guide. If you only needed the fence syntax in the abstract, Mermaid in Markdown is that page. An issue is a conversation with a narrow column and a preview button you can forget to press.

I use an issue diagram when the thread is deciding a branch and the words have started to loop. I do not use an issue as the long-term home of a system map. Closed issues are a bad handbook. The picture can start here. It should move when the decision sticks.

Preview, then look at the saved comment

The issue editor shows source while you type. GitLab draws the diagram on preview, and it draws it again on the saved description or the saved comment. Those are two checks, and I have skipped the second one often enough to deserve the rework. Preview can be a step ahead of what you last toggled, and a comment edited after you previewed will save the edit, not the memory of the preview. Open the preview, submit, then read the comment on the issue page as if you were the person who did not write it.

The opening line is three backticks and the word mermaid, lowercase. The next lines are the diagram. The closing line is three backticks. A fence wrapped inside another fence becomes a code sample about Mermaid, which is a useful way to teach and a useless way to show the deploy path. If the saved comment shows the words flowchart as text, the info string is missing or the fence is nested. Fix that before you restyle a single node.

Draft anything longer than a handful of nodes in the editor first. The preview there is live, and a bad line is easier to see than it is inside a comment box. Paste the finished fence into the issue. The editor does not replace GitLab's renderer. It tells you the syntax is legal in a current Mermaid. GitLab tells you whether this project will draw it. I want both answers before I ask a teammate to approve a plan from the picture.

A comment is a second copy

The description is what people see when they open the issue. A comment is what they see if they read the thread. Those audiences overlap and they are not the same. I put the current plan in the description when the diagram is the proposal. I put a diagram in a comment when I am answering "what did you mean by step three?" and the answer is a branch the description smeared.

The failure mode is a comment that changes the plan while the description keeps yesterday's chart. New readers trust the top of the issue. They will implement the stale branch and feel gaslit by the thread. If a comment changes the decision, edit the description in the same sitting, or say in the comment that the description is now wrong and then actually edit it. I have written "see below" on a description and watched the useful diagram sink under twenty later comments. "See below" is not a link. Update the top, or put a real link to the comment and accept that you are sending people scrolling.

Two fences in one comment are two diagrams. A blank line between them keeps the second opening fence from sticking to the previous paragraph. One keyword per fence. A flowchart and a sequence in the same fence fail, and the error looks like GitLab "does not support Mermaid" when the support is fine and the paste is not.

The wiki is a different lifespan

The wiki renders the same fence. The difference is why the page exists. A wiki page is a handbook you expect to read next quarter. An issue is a conversation you expect to close. A deploy diagram whose only copy is an issue comment will vanish from daily use the day the issue closes, even though the URL still works. I sketch in the issue while the branch is under debate. When the team agrees, I move the source into the repo or the wiki and I leave a one-line pointer in the issue.

Updating the issue does not update the wiki, and the reverse is also true. There is no shared diagram object behind them. I pick one source of truth and I write that choice at the top of the other copy, with a link. Two living copies is how an incident write-up cites the order from March and the pipeline follows the order from June.

Merge requests are the third surface, closer to a review than to a handbook. The same width problem shows up there. The GitLab guide covers that surface together with the repo file. I mention it so you do not think an issue-only habit covers a merge request description. It does not. Preview that description too. The button feels familiar and the column is still narrow.

Version skew, without a version number

GitLab's Mermaid build can differ from the one GitHub bundles. GitLab.com and a self-managed instance can differ from each other, because they can be on different releases, which means they can be on different Mermaid builds. I am not going to quote those version numbers. They move, and a number in this page would become a rumor. The practical test is the issue on the instance your teammate will open.

A fence you proved in the editor, or on a public project, can still fail on a company instance that has not upgraded. Flowcharts and sequence diagrams travel with the least pain. New diagram types fail first. Theme frontmatter and init directives are optional syntax an older build can reject. If the issue shows an error, delete the config block and preview the bare diagram. Add style back only on an instance that accepts it.

"It works on GitHub" is a useful bug report and a weak proof. Ask them to open the GitLab issue. Agreement between hosts is common for a plain flowchart and unreliable for anything Mermaid added recently. When the instance will not draw a legal chart, export a PNG and attach it, and keep the fence in the comment as the source for the day the instance catches up. The Mermaid to PNG tool renders in the browser. Say which file is the source so nobody edits the image by hand and calls it done.

Click stays off, and wide charts do not fit the thread

Click callbacks are disabled. A click line that runs a script or even acts as a link in a local tool will not do that job on GitLab. The nodes can still draw. The callback does not run. I treat that as a security choice and I stop pasting click into issue fences. If a box needs a destination, write a Markdown link under the fence. The issue already knows how to be a link. The diagram does not need to be one.

HTML labels are the wrong tool in a thread. They fail or they look like a smuggled page. Plain text in the node, sentence under the fence. The same goes for a font you set in frontmatter. The issue page has a theme. Fight it and you will win on your monitor and lose on your reviewer's.

Width is the limit I hit most. An issue body is a column, and a comment is that column again, sometimes narrower. Eight nodes left to right become a scrollbar. People do not discover a branch that lives off to the right. I switch the direction to top-to-bottom, I shorten every label to a few words, and I split the chart at a real seam. "Request path" and "failure path" as two fences in the description beat one fence you have to drag.

I do not know a pixel width worth memorizing. Drag the browser to the width you use on a laptop and read the saved issue, not the editor's full-screen preview. If you are scrolling sideways, the chart is too wide for this thread. A mural can live in the repo, where a README has more room, or as an attached image with the source beside it. The issue should hold the decision, and the decision should fit on the screen where the decision is made.

A chart I would paste into a description

This is a triage decision small enough for a comment. It is the sort of thing a support issue argues about in prose for forty messages. The diamond is the argument. The rest is bookkeeping.

flowchart TD
  arrive[Ticket arrives] --> blocked{"Customer blocked?"}
  blocked -->|Yes| page[Page on-call]
  blocked -->|No| wait[Leave for the shift]
  page --> known{"Workaround exists?"}
  wait --> known
  known -->|Yes| send[Send the workaround]
  known -->|No| hand[Hand to engineering]

I would put that fence in the description, then use a comment for a change of mind. "We no longer page on a workaround" is a one-line edit to the diamond's arrows, made in the description, mentioned in the comment. The comment does not grow a second copy of the whole chart unless the comment is the only place a reviewer will look, which is a habit worth breaking.

The node is hand, not end. The word end closes subgraphs. You do not need a subgraph here, and you still should not spend the id. The day someone wraps "on-call" in a box, a node named end swallows the rest of the file.

When the thread is about a conversation

Some issues are about who calls whom. A flowchart flattens that into boxes. A sequence keeps the speakers, and it still has to fit the column, which means few participants and short verbs. The sequence diagram syntax page is the arrow reference. The picture below is the size I will actually drop into a comment about a password reset.

sequenceDiagram
  actor User
  participant App
  participant Mail as Mailer
  User->>App: Ask for a reset
  alt Account exists
    App->>Mail: Send the link
    Mail-->>User: Deliver the link
  else No matching account
    App-->>User: Show the same notice
  end

The else branch is why this belongs in the issue. Prose kept saying "we email the user" and also "we do not reveal whether the account exists." Those sentences fought until the mail lane stayed empty on the missing-account side. A comment with this fence ended the fight. A paragraph might have ended it too, if anyone had written the paragraph carefully. We had not. The diagram was the careful version.

Keep alt closed with end. A missing closer makes the saved comment show an error, and the thread will debug your fence instead of the product. Preview catches this if you look at the preview. It does not catch it if you submit from memory.

Hosts that are not this issue

Notion's limits are about a code block's view mode and a beta type the page cannot draw. The Notion code block limits are that story. Typora is a desktop preview with its own quirks, covered in the Typora Mermaid note. vscode's built-in preview updates on save and has a security level that can blank a fence. That is the vscode mermaid preview settings note. None of those previews is the GitLab issue your reviewer opens. Use them to draft. Use the issue preview, and then the saved issue, to finish.

The Mermaid format note is about the shape of the text itself. It will not remind you that an issue column is narrow. That reminder is this page. Format can be perfect and the chart can still be the wrong size for the thread.

Leave the thread a picture it can hold

Write the decision in a small fence, preview it, save it, and read it once on the issue page. If the instance will not render the type you chose, switch to a flowchart or attach a PNG. If the chart only fits when the window is full screen on a large monitor, it does not fit the issue.

Open the editor to get the fence right, then paste it into the description you want people to trust. Update that description when a comment changes the branch. The wiki can have the durable copy later. The issue's job is the decision in front of the people who are making it, in a picture they do not have to scroll sideways to believe.