How to write a FlowViz diagram link

Recipe

URL = https://flowviz.app/app#m= + percent-encode(Mermaid source) + %0A

1. Write the Mermaid source as plain text (first line is the diagram type, e.g. flowchart TD). In flowcharts, always put node labels in double quotes, A["Start"] --> B{"Logged in?"}, and write a " inside a label as #quot;. In sequence diagrams, keep every message on one line.
2. Percent-encode the source: every ASCII character except A-Z a-z 0-9 - _ . ~ becomes %XX. A newline is %0A, a space is %20. Never use + for a space. Leave Chinese, Japanese, Korean, emoji and other non-ASCII characters exactly as they are: do not encode them.
3. Also encode ( ) ' * ! as %28 %29 %27 %2A %21.
4. Link = https://flowviz.app/app#m= + the encoded source + %0A (end every link with %0A).
5. Chinese and other non-ASCII text appears in the link as the characters themselves, never as %E… escapes: mindmap%0A%20%20产品计划%0A%20%20%20%20设计%0A.
6. Give it to the user as a markdown link: [Open in FlowViz](https://flowviz.app/app#m=...). No spaces or line breaks inside the URL.

• Percent-encode means JavaScript encodeURIComponent(src) or Python urllib.parse.quote(src, safe=''), plus step 3.
• The trailing %0A protects the diagram's last character from chat apps that glue . ) or " onto the end of a link.
• Encoded ( ) keep a markdown link from ending early; some chat apps also cut links at a bare (.

Mermaid rules that break diagrams

A link can be encoded perfectly and still open an error if the Mermaid inside is invalid. Check these before you encode:

flowchart TD
    A[Click the link (if received)] --> B[Show "Check your inbox"]

flowchart TD
    A["Click the link (if received)"] --> B["Show #quot;Check your inbox#quot;"]

sequenceDiagram
    A->>B: POST /token
    grant_type=authorization_code

sequenceDiagram
    A->>B: POST /token<br/>grant_type=authorization_code

erDiagram
    POST ||--|{ POST_TAG : links to
    POST_TAG }o--|| TAG :

erDiagram
    POST ||--|{ POST_TAG : "links to"
    POST_TAG }o--|| TAG : tags

erDiagram
    POST ||--{ POST_TAG : has

erDiagram
    POST ||--o{ POST_TAG : has
    TAG ||--o{ POST_TAG : "is tagged in"

erDiagram
    TAG {
        int id PK
        string name
        unique
    }

erDiagram
    TAG {
        int id PK
        string name UK
    }

classDiagram
    abstract class Shape {
        +area() double
    }

classDiagram
    class Shape {
        <<abstract>>
        +String name
        +area() double*
    }
    Shape <|-- Circle

sequenceDiagram
    participant Auth as Auth Server
    B->>AUTH: GET /authorize

sequenceDiagram
    participant Auth as Auth Server
    B->>Auth: GET /authorize

Characters that break links

• Common sequences: --> is --%3E, [Start] is %5BStart%5D, 4-space indent is %20%20%20%20.
• Letters, digits and - _ . ~ stay as they are.
• Chinese, Japanese, Korean and emoji go into the link unencoded (A%5B开始%5D). Do not try to work out their UTF-8 bytes: one wrong byte turns a label into a different word. Already-encoded bytes (from code) also work.

How to give the link to the user

• Write the link as a markdown link: [Open in FlowViz](URL). Chat apps render it as clickable text.
• Tell the user the whole diagram lives in the link and nothing is uploaded.
• Put no spaces or line breaks inside the URL, however long it is.
• You may also show the Mermaid source in a mermaid code block so the user can copy it. The link itself must never be inside a code block.

Before sending, check the link:

• Starts with https://flowviz.app/app#m=.
• No spaces, line breaks, raw #, or raw ( ) after #m=.
• The Mermaid inside follows the rules in "Mermaid rules that break diagrams".
• Any Chinese, Japanese, Korean or emoji text is written as the characters themselves, with no %E… escapes you worked out by hand.
• Ends with %0A.
• Is inside [Open in FlowViz](...), not in backticks or a code block.

Common mistakes

• Using + for spaces. FlowViz reads + as a space only when the link has no %20 and no raw space anywhere. Mix the two and every + stays a literal +. Always use %20, and encode a real + as %2B.
• Not encoding # or %. A raw # or % in the source corrupts the link. Write %23 and %25. Also encode & ? = / so the URL stays unambiguous.
• Line breaks or spaces inside the URL. Chat apps end the link at the first space or line break, so the diagram is cut off. Every newline in the source must be %0A and every space %20, so the link is one unbroken line.
• Putting the link in backticks or a code block. Then it is shown as text and the user cannot click it. Use a markdown link [Open in FlowViz](URL) in normal text.
• Very long diagrams. Keep links under about 8,000 characters; some chat apps and browsers cut longer ones. For a bigger diagram, give the user the Mermaid code in a code block and tell them to paste it into the editor at https://flowviz.app/app.
• Encoding the prefix. Only the diagram is encoded. https://flowviz.app/app#m= is written exactly as shown, then the encoded source, then %0A.

If you can run code

If you can run code, generate the link instead of encoding by hand. Both snippets print the same link as the recipe above.

Python

from urllib.parse import quote
source = """flowchart TD
    A[Start] --> B[End]"""
link = "https://flowviz.app/app#m=" + quote(source + "\n", safe="")
print(f"[Open in FlowViz]({link})")

JavaScript

const source = `flowchart TD
    A[Start] --> B[End]`;
const encoded = encodeURIComponent(source + "\n")
  .replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
const link = "https://flowviz.app/app#m=" + encoded;
console.log(`[Open in FlowViz](${link})`);

The Share button in the FlowViz editor makes a shorter, compressed link. Don't try to write compressed links (#z= or ?d=) by hand. Use #m=.

Other formats FlowViz opens

• https://flowviz.app/app#z=…: Compressed (DEFLATE with a checksum), generated by FlowViz. Opens as-is; do not write one by hand.
• https://flowviz.app/app#pako:…: A Mermaid Live Editor link. Replace https://mermaid.live/edit with https://flowviz.app/app and keep everything from #pako: on.
• https://flowviz.app/app?d=…: Older FlowViz links (lz-string compressed). They still open, but new links should use #m=.
• https://flowviz.app/s/<id>: Short links the user creates in the editor. These are the one case where a diagram is stored on the server; stored copies are deleted after 3 months.

For developers

FlowViz reads a diagram from the URL fragment (after #), which browsers never send to a server, so opening a link your code, extension or bot built makes no request that carries the diagram. Links open at https://flowviz.app/app.

Link formats

• #m=<percent-encoded source>: Plain. Build it with encodeURIComponent in any language, following the Recipe. The decoder is lenient about the mistakes people and models make: raw spaces and newlines, + for space, a Markdown code fence around the whole diagram, and punctuation a chat app glues onto the end.
• #z=<data>: Compressed, written by the editor's Share button: base64url (no padding) of the raw DEFLATE (level 9) of the UTF-8 source, followed by the 4-byte big-endian CRC32 of the compressed bytes. Usually much shorter than the same diagram as #m=. A link that fails the checksum is refused rather than opened as a slightly different diagram.

Mermaid Live import

• A Mermaid Live Editor link opens in FlowViz: replace https://mermaid.live/edit with https://flowviz.app/app and keep everything from #pako: on. The older #base64: form works the same way.
• Pasting a Mermaid Live URL into the FlowViz code editor offers to import it.
• FlowViz takes the diagram code, and the Mermaid Live theme when FlowViz has the same one. Other Mermaid Live settings are ignored.

Query parameters

• ref: Where the link came from, for example ref=chatgpt or ref=my-extension. A short slug: lowercase letters, digits and - _ ., up to 40 characters. Anything else is ignored. It is counted in FlowViz's analytics together with whether the link opened.
• theme: The FlowViz theme to open in, by slug: default, neutral, forest, base, ocean, sunset, high-contrast, monochrome, dark, purple. Case doesn't matter, and old theme names still work (for example dark-protocol, ocean-breeze). An unknown value is ignored and the visitor keeps their own theme. Slugs never change. See every theme at https://flowviz.app/themes.
• view: edit or preview: which pane a phone shows first. Desktop always shows both.

Query parameters go before the #, for example https://flowviz.app/app?ref=my-extension#m=.... They take effect only when the link carries a diagram. Unlike the fragment, the query is sent to the server, so never put diagram text in it.

JavaScript helper

function flowvizLink(source, ref) {
  const encoded = encodeURIComponent(source + "\n")
    .replace(/[!'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
  const query = ref ? "?ref=" + encodeURIComponent(ref) : "";
  return "https://flowviz.app/app" + query + "#m=" + encoded;
}

console.log(flowvizLink("sequenceDiagram\n    Alice->>Bob: Hi", "my-extension"));

Privacy

The diagram travels in the URL fragment (the part after #), which browsers never send to a server. FlowViz opens it entirely in the browser.