How typora mermaid blocks render, and where they stop

What I mean by typora mermaid, in the notes I actually keep, is a fenced code block whose language tag is mermaid. You write the diagram as text, Typora draws it in the preview when Mermaid is turned on, and the source stays in the Markdown file you can commit. If the fence stays as a gray code block, don't rewrite the syntax yet. Check Typora's Mermaid setting in the version you have. A preference that is off looks exactly like a parse error, and it isn't one.

The fence people actually use

The block starts with three backticks and the word mermaid on that same line. It ends with three backticks on their own line. The first line inside is a diagram keyword such as flowchart or sequenceDiagram. There is no separate Typora-only dialect I am willing to describe. The same fence renders in other Markdown hosts that support Mermaid, which is why I keep the source boring.

In the note you only have one fence, tagged mermaid, with the diagram inside. The usual mistake is a fence tagged text, or a fence with no tag, or the word mermaid written on the line after the backticks instead of on the same line. Typora then has no reason to treat the block as a diagram. It shows code. The diagram can be perfect and still look like a snippet you forgot to run.

I don't invent a menu path for the switch. Typora versions move preferences around, and a blog that says "click this exact checkbox" becomes a lie the next time the app is rearranged. If the block stays as code, open the preferences you do have and look for a Mermaid setting. Turn it on. Reopen the note if the preview doesn't refresh. Then, and only then, blame the syntax.

The Mermaid in Markdown guide is the host-neutral version of the fence rules: the tag, the keyword, what happens when a config block sits in the wrong place. Use it when the same file has to render in Typora and somewhere else. This page stays on Typora's habits, including the ones that are easy to misdiagnose.

When the block stays as code

Work through the causes in this order. I have watched people "fix" a valid diagram for twenty minutes because they skipped the first one.

The language tag is missing or wrong. mermaid is the tag. Mermaid may work, and I still type it in lowercase so I don't have to care. mmd is not the tag I use. If you aren't sure what you typed, look at the first line of the fence in source mode, not in the preview. Preview will hide the fence once it succeeds, which is useless while it is failing.

The setting is off. This is the one that feels like a bug. The fence is correct, another note from a year ago still shows a picture, and the new note shows code. The old note may have been exported to HTML back when the setting was on, or you may be looking at a cached preview. Check the setting before you delete lines. I keep a tiny known-good flowchart in a scratch note for this. If the scratch note also stays as code, the problem is Typora's setting or that install, not the billing diagram you just wrote.

The keyword inside is wrong. flowchart TD and sequenceDiagram are real. A diagram type Mermaid added recently may be ahead of the Mermaid build bundled in your Typora version. If a simple flowchart renders and a newer diagram type doesn't, believe the version gap. Simplify the diagram or export a picture from a current renderer. Don't keep adding syntax to a block the bundled library cannot parse.

A config header at the top of the fence is the last thing I try removing. Theme frontmatter and init directives are legal Mermaid and a common way to get a block that one host draws and another shows as an error. If you need a theme, set it in the editor you use for export, and keep the committed fence plain. The note stays portable. The pretty colors can be a local choice.

A flowchart in a note

This is the kind of flowchart I drop into a Typora design note. It is small enough to read next to a paragraph, and it doesn't depend on a theme. The question is whether a draft is ready. The back-edge is the interesting part: not ready means you are still in the draft.

flowchart TD
    draft[Draft the note] --> review{Ready to share?}
    review -->|No| draft
    review -->|Yes| ship[Commit the note]

Ids are draft, review, and ship. Labels are the words a reader needs. I didn't use a node called end. In Mermaid that word closes a subgraph, and a note you will edit later is exactly where that bug shows up, months after you forgot the rule. ship is a fine id. The label can say "Commit the note" without the id matching it.

Parentheses in a label need quotes. ship[Commit the note] is safe. ship[Commit (docs)] is the form that surprises people, because the parentheses look like shape syntax. If you need the parentheses, write ship["Commit (docs)"]. I avoid them unless the name really has them. A note about Typora doesn't need a parenthetical in the box.

I put one diagram per section. Typora notes get long, and a fence in the middle of a sentence is miserable to edit in source mode. A heading, a short paragraph, the fence, a paragraph that says what the diamond means. The diagram is not the section. The paragraph is, and the diagram is the part that would have been an indented list with a branch.

A sequence when the note is a conversation

Flowcharts are the default people paste. Sequences are the ones that earn a note when the draft is about who calls whom. A Typora doc for a login change should not be twelve boxes named Browser, App, and Auth in a flowchart. It should be lifelines. The same fence tag is doing the work. Only the keyword changes.

sequenceDiagram
    participant Author
    participant File
    participant Preview
    Author->>File: Save the fence
    File->>Preview: Ask for a render
    Preview-->>Author: Show the diagram

->> is the solid arrow, the request. -->> is the dotted arrow, the reply. I keep that distinction even in a note about note-taking, because the habit is the point. If every arrow is solid, a reply looks like new work. The preview isn't doing a second job. It is answering.

The middle participant is File, not Note. Mermaid treats note as a keyword for a comment beside a lifeline. Author->>Note: fails the parse even after participant Note, and the error talks about a note instead of an actor. Rename it. The file is what you saved anyway.

Participants are declared first, in the order I want them on the page. If I let the first message invent the cast, a participant I mention late jumps to the right and the story reads backwards. In a Typora window that is already narrow, order matters more than it does in a wide browser preview. Declare the three lines. Then write the messages.

Message text stays short. "Save the fence" fits. A message that includes the whole file path and a parenthetical will push the lifelines apart until the note is a horizontal scrollbar. Put the path in the prose under the fence. The arrow is a verb.

If this preview conversation is too cute for the doc you are writing, replace the names with the real system and keep the arrows. Browser, App, Auth, a solid login, a dotted session. The Typora part is the fence, not the domain. The domain should be whatever the note is about.

Versions, themes, and what not to blame

Typora bundles a Mermaid build. I am not going to guess which one you have, and I am not going to publish a version number I looked up once and will forget to update. The practical test is the scratch note. A two-node flowchart is the compatibility check. If that works, your syntax is the next suspect. If that fails, the setting or the install is the suspect.

New diagram types are the version trap. Mindmaps, block diagrams, architecture diagrams, and anything Mermaid shipped recently may render in a current web editor and sit as an error inside Typora until the app updates. I don't fight that in the note. I keep the note's diagrams on flowchart and sequence, which have been stable for years, and I link out if a design doc truly needs a grid. You can also paste the newer diagram into a renderer that is current and commit an image beside the source. Say in the paragraph which file is the source of truth. Two undeclared sources is how the note and the image disagree by Thursday.

Themes are a similar trap. A dark theme that looks right in Typora can be unreadable in a light export, or the reverse. I leave theme directives out of the fence. If the preview colors bother you, change them in the app if your version offers that, and accept that the committed file stays on the default. Portable source beats a local palette. The format notes are where I look when a fence is valid and still ugly: line breaks, ids, labels, the stuff that survives a host upgrade.

GitLab and VS Code fail differently, which is useful to know so you don't "fix" a Typora note into a shape that only one of them accepts. Mermaid in GitLab issues is about fences inside issue text, where a blank line or a special character can eat the block. VS Code preview settings is about an editor preview that has its own switch and its own bundled build. The habit transfers. The menu names do not. Check the product you have open. Don't paste a Typora click-path into a VS Code argument, or the reverse.

Notion is the comparison I use when someone says "just embed it." Notion's code block limits are real and they are not Typora's problem. Typora is a Markdown file. The fence is the file. You are not negotiating with a block type that stores a drawing separately from the text. That is the reason I still use it for design notes I intend to commit.

Export without guessing the dialog

Typora can export a note. What that export does with a Mermaid fence depends on the version: some builds rasterize, some leave a code block, some produce HTML that only looks right in a browser with the right script. I am not going to describe a dialog box I cannot see on your machine. Check the version. Try one export on the scratch note. If the picture survives in the format you needed, you are done, and you didn't need this site.

When you need a predictable SVG or PDF, I don't use the note export as the archive. I paste the fence into a renderer that tells me the format up front. JPG, SVG, and PDF from MermaidViewer are Pro-only. PNG exists on every plan: the free plan is 1× with a small watermark, and Starter at $6.99 a month is watermark-free up to 4×. Pro is $11.99 a month. I mention the prices because "export the picture" is otherwise a shrug. The export guide is the long version of those format tradeoffs. The PNG converter and the SVG converter are the direct tools when you already know which file you want.

SVG is what I want if the diagram might be scaled in a slide or a design tool. PDF is what I want if someone asked for a page. PNG is what I want if the destination is a ticket system that only accepts images. None of that requires me to claim that Typora's export dialog has a particular checkbox. If your Typora version already produces a sharp SVG you like, keep using it. The point of a second tool is the case where the export is a surprise.

Share links are a different path. They are fine for a review comment. They are a bad substitute for the fence in the repo. The note should contain the source. A link can rot, or it can point at a newer edit than the commit you are reading. I have debugged that. The commit had the old fence, the link had the new one, and the argument was about a diamond that existed in only one of them.

Notes that still belong in git

Typora is a local editor. The file is the artifact. I commit the Markdown, not a Typora-specific package, and I don't depend on an unpublished setting to make the file true. Anyone with a Mermaid preview can read the fence. Anyone without one can still read the labels as text, which is a weak fallback and better than a binary drawing.

I keep diagrams near the paragraph that uses them. A long note with an appendix of twenty fences is a slide deck in denial. Each fence answers the paragraph above it. If the paragraph doesn't need a branch or a conversation, delete the fence. Typora makes diagrams easy enough that I draw them when a list would have been clearer. The setting being on is not a reason to diagram the grocery list.

Source mode and preview mode will both lie to you in small ways. Source mode shows the fence and not the layout bug. Preview mode shows the layout and hides a missing quote until you scroll. I edit in source, glance at preview, and if preview disagrees with what I think I typed, I go back to source before I "fix" the picture by adding nodes. The text is the spec. The preview is a rendering. When they conflict, I want to know which one I changed last.

If a block still will not render after the setting is on and the scratch flowchart works, the next step is a real syntax check, not another preference hunt. Paste the fence into the editor. The preview there is current, and the error is usually a missing colon, an unquoted label, or a diagram type your Typora build has not caught up to. Fix the text. Put it back in the note. If the web preview works and Typora still shows code, you have your answer: the setting, or the bundled version. Stop rewriting a diagram that was already fine.