How to Publish Mermaid Diagrams in Substack Emails

Why a static image is the dependable format

On a documentation site, a Mermaid library reads the diagram source and creates SVG in the browser. An email client generally does not run arbitrary JavaScript, and Substack’s post editor is not a Mermaid renderer. Pasting the source therefore produces code or plain text, not a flowchart.

SVG is excellent on the web but has uneven support and security treatment across publishing and email systems. A sufficiently large PNG sacrifices infinite scaling, yet it is broadly predictable. Keep the original Mermaid source in your repository or vault so the diagram remains editable.

Start with a focused Mermaid block

The diagram has one reading direction, four nodes, short labels, and no decorative subgraph. That simplicity is a feature in an email column. If the explanation needs many branches, publish two diagrams that answer separate questions.

```mermaid
flowchart LR
  Draft[Markdown draft] --> Check[Publishing checks]
  Check --> Copy[Rich-text copy]
  Copy --> Post[Substack post]
  Post --> Email[Test email]
```

Convert Mermaid to a Substack-ready asset

1. 01

   Keep the language marker

   Use mermaid immediately after the opening code fence so the converter can distinguish diagram source from ordinary code.

2. 02

   Load the full post into StackDraft

   The preview detects each Mermaid block and renders it locally. No unpublished diagram source needs to be sent to a conversion service.

3. 03

   Inspect the generated diagram

   Check labels, edge direction, contrast, and the smallest text. Fix the Mermaid source rather than trying to repair a raster image.

4. 04

   Copy or export the prepared asset

   Use the prepared body for the publishing handoff. StackDraft also lists generated assets so you can export them when a manual upload is more reliable.

5. 05

   Add context and alt text in Substack

   Introduce the question the diagram answers, add a concise image description, and explain the important path or conclusion in normal text.

6. 06

   Check the test email

   Open the message on a phone and confirm every label is legible at the displayed width without zooming.

Design diagrams for a narrow newsletter

• Use left-to-right flow for short pipelines and top-to-bottom flow for branching systems.
• Keep labels to a few words; put explanations in the article body.
• Prefer a small number of meaningful nodes over a complete architecture inventory.
• Avoid pale text, hairline edges, and color combinations that disappear in dark mode.
• Do not encode categories with color alone; use labels, shapes, or line styles too.
• Split sequence diagrams with many participants into separate interactions.
• Keep one diagram focused on one claim or process.

Provide a useful text alternative

A diagram description should communicate its purpose and important relationships. For the example above, useful alt text would be: ‘Publishing flow from a Markdown draft through compatibility checks and rich-text copy to a Substack post and test email.’ That is more informative than ‘flowchart’ and more concise than listing every visual property.

Complex diagrams need an adjacent prose explanation, not an enormous alt-text transcript. Describe the main path, decision, or conclusion in the article so readers who cannot inspect the image receive the same core insight.

Troubleshoot Mermaid publishing failures

1. 01

   The block appears as code

   Confirm the opening fence is labeled mermaid and preview it in StackDraft before copying to Substack.

2. 02

   Rendering reports a syntax error

   Reduce the diagram to the smallest valid version, then add nodes and edges back until the failing line is clear.

3. 03

   The PNG is too dense

   Remove secondary detail, shorten labels, change direction, or split the diagram. Raising resolution cannot rescue an overloaded information design.

4. 04

   PNG export falls back to SVG

   Reload and retry in a current desktop browser. If the browser blocks rasterization, export the listed SVG asset and convert it to PNG before uploading.

5. 05

   The image is present but unclear in email

   Increase label contrast and simplify the source for the actual displayed width, then replace the asset and send another test.