Notion mermaid code block limits that show up after setup

The failures people mean by notion mermaid code block limits show up after the diagram already works somewhere else. A code block with the language set to Mermaid can draw a flowchart, and the block can sit in Code, Split, or Preview. That is the feature. The limits are what happen next: a beta diagram type that the page will not draw, a theme or frontmatter block that blanks an otherwise fine chart, a picture too large for the column, a view mode left on Code so readers see source, and a click line that never runs. I treat those as the job. The setup steps, the /code menu and the first paste, live in the Mermaid in Notion guide. Come back here when the block exists and the picture is wrong, cramped, or missing.

I am not going to invent a character cap. Notion has not handed me a number I am willing to print, and a number I guessed would be worse than none. Size is a reading problem before it is a quota. If you cannot read the labels in the column where the page actually sits, the diagram is too big for that page, whatever the counter says.

What the block will and will not do

The language menu is what tells Notion to render. The body of the block starts with a diagram keyword such as flowchart or sequenceDiagram. A Markdown fence inside the block is the wrong shape, because the block is already the code container. Code mode shows the source. Preview shows the drawing and hides the source. Split shows both, which is the mode I use while a label is still moving.

Those three modes are the whole interface I rely on. There is no separate diagram object, no shared library of nodes, and no promise that a type Mermaid shipped last month exists in the Notion build you have today. Flowcharts and sequence diagrams are the ones I trust on a page other people will open. When I need a newer type, I prove it in the editor first. The editor's preview is live and it will tell me whether the syntax is legal at all. Notion tells me whether this workspace will draw it. Those are different answers, and I have wasted a standup confusing them.

Click callbacks do not run. A click line that opens a URL or calls a script in a local tool stays inert on the Notion page. That is a platform choice, and fighting it with a cleverer line will not produce a button. If a node needs a destination, write a normal link in the paragraph under the block. The diagram remains a picture. The sentence remains the link. I stopped putting click in anything I paste here, including diagrams that "worked on my machine," because the machine in question was not Notion.

Beta types fail before the classics do

block-beta, architecture-beta, and other young diagram types are the first to come back as an error or as untouched source. I do not keep a matrix of which Notion release accepts which keyword. The matrix would be stale by the time I finished it. The test is shorter than the matrix: paste the smallest example of that type into a scratch page, in Split, and look.

If the scratch page fails, the long version will fail. Export a picture and drop the picture on the page, or redraw the idea as a flowchart or a sequence if the idea can survive the change. A tier stack can often become a top-to-bottom flowchart with a subgraph per tier. You lose the strict grid. You keep a picture the team can see. I would rather have the coarser picture on the wiki people open than a perfect grid that renders as a code block.

A failure on a beta type is not a reason to rewrite a flowchart that was fine. Check the keyword on line one. I have "debugged" a healthy flowchart for twenty minutes because the block's language was still Plain text. The language menu is a limit of a boring kind. It still counts. Preview cannot rescue a block Notion does not believe is Mermaid.

Theme and frontmatter blank a valid chart

Theme config and diagram frontmatter are useful in a dedicated editor. They are also optional syntax a Notion build can reject. The symptom is a block that drew yesterday and draws nothing after you pasted a style you liked elsewhere: a frontmatter block at the top, or an init directive that sets a theme. The nodes were never the problem. The header was.

Strip the config. Leave the keyword and the nodes. If the picture returns, the theme was the limit, and you have your answer. Add style back only if this page still draws, one change at a time. I keep a copy of the styled version in the editor, where I can use it, and I paste the plain version into Notion. Two sources sound fussy until you have told a teammate their syntax is wrong when the syntax was a theme name Notion had not caught up to.

Hard-coded fills have a second problem that is not a parse error. Notion pages follow the reader's theme. A pale box with gray text can disappear, or a dark fill can look like a hole. If I need status, I put the status in the label. "Approved" and "Blocked" do not need paint. When the page is a runbook someone will open at night on a dark theme, I assume the default colors and I check Split in that theme before I call the block done.

The syntax errors guide is the list I use when the message is a real parse error rather than a theme the host skipped. Missing quotes, a node named end, a subgraph that never closes. Fix those in the editor, where the bad line is easier to see, then paste the repaired source back. Notion's error surface is enough to know it failed. It is a poor place to learn which bracket you dropped.

Wide charts become a stripe

Notion columns are narrower than a blog post and much narrower than a monitor you used while drafting. A left-to-right flowchart with a sentence in every node turns into a sideways scroll or a stack of tiny type. I do not know a magic node count where this starts. I know the symptom: you zoom the browser and you still cannot read the diamond.

Shorten labels first. The node says "Card accepted?" and the paragraph says what accepted means for this merchant. Then change direction. Top to bottom uses the vertical space a Notion page already has. Then split the chart at a real boundary. Checkout payment and checkout fulfillment are two blocks, one under the other, with a sentence between them. A single mural of the whole company will not become readable because you toggled Split.

Sequence diagrams have the same illness when you add twelve participants. The lifelines shrink and the message text overlaps. Declare only the actors this paragraph needs. A second sequence under the first, for the failure path, is easier to read than one sequence that tries to be the failure path in an alt with six lanes. I split when I feel myself shrinking the browser font. That feeling is the limit. A quota would be nicer. Reading is the one I can apply today.

This is the size I am willing to put in a Notion column. Four questions would be a different page.

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]

If that small chart fails, stop editing nodes. Check the language and the view mode. If a much wider chart fails only by being unreadable, the parser is fine and the column is the limit. Rewrite or export. Do not keep adding nodes until Notion "catches up." It will not catch up to a mural.

Code, Split, and Preview left on by accident

The mode sticks. I paste a finished diagram, admire it in Split, and leave the block on Code. The next person opens the page and reads arrows and brackets where they expected a picture. That is the most common failure I see, and it is not a Mermaid bug. Switch to Preview when you stop editing. Split is for the author who is still changing a word. Preview is for the page.

The reverse mistake is also mine. I leave Preview on, then I try to fix a label and I am hunting for the source. Code is one toggle away. I still lose a minute and blame the page. Make the toggle part of the habit: edit in Code or Split, read in Preview, and look at the block once after you click away. Notion redraws when you leave the block, which is a slower loop than a live preview. For anything past a handful of nodes I draft in the editor and paste the result. The slower loop is fine for a one-line label change. It is a poor place to design the branch.

A block left on Code is especially confusing next to a real code sample. Readers cannot tell which fence is a diagram that failed and which is TypeScript you meant to show. Preview removes the ambiguity. If you must show the source as a teaching aid, put a short snippet in a plain code block underneath and keep the Mermaid block on Preview. Two blocks, two jobs.

When the page will not draw, export a picture

Some diagrams will not render in Notion no matter how plain you make them, because the type is too new or the build is too old. Stop pasting variations. Render the picture elsewhere and put the image on the page. The Mermaid to PNG tool does that in the browser. PNG works on every plan. Free export is 1× with a watermark. Starter, at $6.99 a month, is watermark-free up to 4×. JPG, SVG, and PDF are Pro-only, at $11.99 a month. If the page only needs a readable snapshot, a watermarked PNG is an honest outcome. Say next to the image that the text source lives in the editor or in the repo, and date the snapshot. An image does not update when the code block would have.

I prefer the code block whenever Notion can draw it, because the next edit is a text edit. I switch to PNG when the alternative is a page full of source or an error. Leaving the broken block "until Notion supports it" means the runbook is wrong for the whole wait. The image is the workaround. The source stays the source, somewhere the renderer is current.

The same export helps when the diagram is legal and merely too wide. A PNG can be a full-size picture the reader opens, while the page keeps a shorter flowchart. Do not upload a PNG of unreadable text and call it accessibility. Shorten the chart, then export if you still need a file for a deck or a ticket that will not render Mermaid.

GitLab issues, Typora, and vscode each have their own preview habits. The GitLab issues note, the Typora Mermaid note, and the vscode mermaid preview settings note are those habits. Notion's special constraint is the block mode and the column. Copying a fence from a README into a Notion code block without removing the backticks is a classic way to confuse all of them in one paste. The render Mermaid diagram overview is the three-path version, browser, host, and CLI, when Notion is only one of the hosts you have to satisfy.

A sequence that fits the column

Who talks to whom survives in Notion if the cast is small. This is the reset path I would put under a support runbook. The branch is the point. The theme header is absent on purpose.

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

One keyword, one block. A second diagram on the page is a second code block. Two keywords in one block fail, and the failure looks like a limit when it is a paste mistake. Under the block, write the rule the arrows cannot hold, such as "do not reset an account from a forwarded screenshot." That sentence is not a Mermaid feature. It is the runbook.

The flowchart syntax page is where I check a shape before I blame Notion. Parallelograms, cylinders, and quoted labels that work in the editor and fail here are still worth simplifying. If a fancy shape is the only thing Notion rejected, replace the shape with a rectangle and keep the word. The word was the content.

What I check before I share the page

I have a short pass, and I do it in the same order every time so I do not "fix" syntax that was never broken.

1. Language is Mermaid, and the body starts with the diagram keyword, not with backticks.
2. The view mode is Preview if anyone else will open the page today.
3. The keyword is a type this scratch page has already drawn. Beta types get a test, not a hope.
4. There is no theme frontmatter and no init directive on the Notion copy.
5. Labels are short enough to read in the column without horizontal scrolling.
6. There is no click line. Links sit in the paragraph under the block.
7. If the block still will not draw, a PNG is on the page and the source is named.

That pass is the limit-handling. The happy path is still the one in the setup guide: one block, Preview, a chart that matches the paragraph above it. When the pass fails on step 7, I stop arguing with the block. The page has to help the reader today. A watermark on a temporary PNG bothers me less than a runbook that shows source to the person holding the pager.

Open the editor when the Notion loop gets slow. Draft there, confirm the picture, paste the plain source into the code block, and switch that block to Preview before you leave the page. If the workspace cannot draw it, export the PNG and move on. The diagram's job was the decision, not the demonstration that Notion and Mermaid share a release train.