Technical Diagrams In Notion

Purpose

This guide explains how to use Mermaid, Git, Notion, and AI together to create a repeatable diagramming workflow.

The goal is not to make one-off diagrams. The goal is to create a small diagramming system:

• Mermaid provides diagrams as text.

• Git stores the source of truth.

• Notion presents diagrams inside project documentation.

• AI generates, refactors, and applies your house style.

• Mermaid Chart or Mermaid Live Editor gives a fast visual preview when useful.

• Mermaid CLI renders stable SVG, PNG, or PDF exports when Notion rendering is not enough.

The core principle is simple:

Notion is the publishing layer, Git is the source of truth, and AI is the accelerator.

Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired text definitions to generate diagrams, and Mermaid’s own documentation frames its purpose as helping documentation keep pace with development. Mermaid’s official docs also describe Mermaid Chart as a browser-based editor with AI diagramming, collaboration, multi-user editing, and storage features.

What Is Mermaid?

Mermaid is a text-based diagramming language. Instead of drawing boxes and arrows manually, you write a small block of code that describes the diagram. A renderer then turns that code into a visual diagram.

A simple Mermaid diagram looks like this:

That source text can be copied, reviewed, committed to Git, generated by AI, embedded in Markdown, rendered in many tools, and updated as the underlying system changes.

This is the main advantage over drawing tools. A PNG, screenshot, or Figma frame can explain something visually, but it is hard to diff, automate, refactor, or keep in sync with implementation. Mermaid diagrams behave more like code. They are plain text, versionable, reusable, and cheap to regenerate.

Mermaid is especially useful for:

• System architecture diagrams.

• Agent workflows.

• Data pipelines.

• API request flows.

• Sequence diagrams.

• Decision trees.

• State machines.

• User journeys.

• Deployment diagrams.

• Documentation diagrams that should evolve with the system.

It is less suitable for:

• Highly polished brand illustrations.

• Complex spatial layouts.

• Architectural drawings.

• Geometry-heavy diagrams.

• Diagrams where exact manual positioning is essential.

• Presentation visuals that need heavy custom art direction.

The practical rule:

Use Mermaid when the diagram represents logic, flow, architecture, dependency, state, or process.

Why Use Mermaid With Notion

Notion is useful for project documentation because it keeps context close to planning, writing, research, and execution. Mermaid adds structure to that documentation.

A Notion page can contain:

• The problem being solved.

• The implementation notes.

• The Mermaid diagram preview.

• The Mermaid source code.

• A link to the Git source file.

• The prompt used to generate or update the diagram.

• Notes about what changed.

That makes diagrams part of the working system rather than decorative attachments.

The problem is that Notion should not be treated as the canonical storage location for the diagram source. Notion pages are easy to edit, but they are not a good source of truth for technical assets that should be reviewed, diffed, reused, and kept consistent across projects.

The better model is:

This gives you a clean division of responsibility:

What The Free Editor Can And Cannot Do

The free Mermaid editor is useful, but it should not become the system of record.

Use the editor for:

• Drafting a diagram quickly.

• Checking whether Mermaid syntax renders.

• Trying layout directions.

• Copying a diagram into Notion.

• Exploring new Mermaid diagram types.

• Visual sanity checks.

Do not rely on the free editor for:

• Long-term storage.

• Style governance.

• Version history.

• Shared design-system enforcement.

• Canonical client deliverables.

• Automated rendering.

Mermaid itself does not work like CSS modules or React components. You cannot usually write one global style file and import it into every Mermaid block inside Notion. For Notion usage, each diagram should either contain its own styling block or be generated from a template that injects the standard styling.

This is the key implementation reality:

Mermaid style reuse is mostly a workflow problem, not a built-in import system.

The solution is to store styles, templates, and AI instructions in Git, then use AI or scripts to apply them consistently.

Recommended Architecture

Use Git as the diagram design-system repository.

A practical repository structure:

This structure separates reusable assets from actual diagrams:

Mermaid Styling Basics

Mermaid has several styling mechanisms. For this workflow, the most useful are:

1. Theme configuration.

2. themeVariables.

3. classDef.

4. class.

5. Link styles.

6. Frontmatter config.

Mermaid’s official theming documentation states that themes can be configured site-wide or per diagram, that diagram-specific customisation can use frontmatter config, and that the base theme is the modifiable theme for custom themeVariables.

Theme Configuration

Use base when you want to define your own colours and typography.

Example:

For Notion, diagram-specific frontmatter is often the simplest approach because the config travels with the diagram. That makes the diagram more portable.

Semantic Classes

The most important styling pattern is not visual. It is semantic.

Instead of styling every node individually, define reusable classes:

This creates a vocabulary:

This is more useful than picking colours ad hoc because the visual system starts carrying meaning.

A Standard Graph Mermaid Style

A good default style should be calm, readable, and suitable for both internal documentation and client-facing work.

Use muted colours, clear contrast, and semantic classes.

This can become the default style that AI applies to new diagrams.

Style File Pattern

Because Mermaid blocks do not reliably import shared style files inside Notion, the styles/ folder should store snippets that are copied or injected.

Example file:

Example file:

AI can then combine:

1. The theme frontmatter.

2. The diagram body.

3. The semantic class definitions.

4. The class assignments.

Diagram Template Pattern

A diagram template should include structure, not just colours.

Example template:

This gives AI a strong pattern to follow.

How To Use This In Notion

There are two practical ways to use Mermaid in Notion.

Option 1: Native Mermaid Code Blocks

Use this when the diagram renders correctly in Notion.

Create a code block and set the language to Mermaid. Paste the Mermaid source.

Recommended Notion page structure:

This is the fastest workflow. It keeps the diagram editable inside Notion.

The limitation is that Notion may not support every newest Mermaid feature immediately. If a diagram works in Mermaid Live Editor but fails in Notion, the likely cause is a version or feature support mismatch. In that case, simplify the diagram or use an exported SVG/PNG.

Option 2: Git Source Plus Exported Image

Use this when the diagram is important, client-facing, or visually sensitive.

Workflow:

1. Store the source in Git as .mmd.

2. Render it to SVG or PNG.

3. Upload or embed the rendered export in Notion.

4. Keep the Git source path visible below the image.

5. Edit the .mmd source, not the Notion image.

Recommended Notion page structure:

This is more reliable for polished documentation because the rendered asset is controlled by your local or CI rendering setup.

Suggested Notion Database

Create a Diagrams database in Notion.

Recommended properties:

Each database item should contain:

This turns diagram maintenance into an operational process.

Using Mermaid Chart Alongside Git

Mermaid Chart can be useful as an editor, especially when you want a browser-based preview or a more visual experience. The safe workflow is:

1. Start from a Git template.

2. Paste into Mermaid Chart or the live editor.

3. Adjust syntax and layout.

4. Copy the final Mermaid source back into Git.

5. Render or paste into Notion.

Avoid this anti-pattern:

Prefer this:

Rendering With Mermaid CLI

For repeatable exports, use Mermaid CLI.

Mermaid CLI takes a Mermaid definition file as input and generates SVG, PNG, or PDF output.

Install locally:

Add scripts to package.json:

Render one diagram:

Render PNG:

Render PDF:

Use SVG for most Notion and website documentation because it scales better. Use PNG for tools that do not handle SVG well. Use PDF for formal reports.

Automating Rendering

A simple render script can scan the diagrams/ folder and render everything.

Example:

Add to package.json:

Run:

This gives you a repeatable export pipeline.

Using AI As A Mermaid Skill

AI is useful because Mermaid diagrams are structured text. The model can generate diagrams, refactor them, simplify them, apply house style, and check for missing flows.

The important part is to give the AI a stable style guide.

Create:

Recommended content:

Then create task-specific prompts.

Diagram Generation Prompt

Diagram Review Prompt

Diagram Refactor Prompt

Custom GPT Or Project Instruction Pattern

If using a custom GPT, ChatGPT Project, Claude Project, Cursor rule, or similar, use a compact instruction block:

This functions as the AI skill.

A Full Example Workflow

Assume you want a diagram for a Fabrify factory workflow.

Step 1: Create The Source File

Create:

Add:

Step 2: Preview The Diagram

Use one of:

• Notion Mermaid code block.

• Mermaid Live Editor.

• Mermaid Chart.

• VS Code extension.

• Mermaid CLI render.

Step 3: Render An Export

Step 4: Add To Notion

In Notion, create a page:owe

Step 5: Commit The Source

Practical Rules For Notion Readability

Notion diagrams need to be simpler than slide-deck diagrams because Notion pages are often read in narrow panes, side peeks, and browser windows with inconsistent widths.

Use these rules:

• Keep most diagrams under 12 to 15 nodes.

• Use short labels.

• Prefer TD for procedural flows.

• Prefer LR for request-response or dependency chains.

• Use subgraphs only when they clarify boundaries.

• Avoid deeply nested subgraphs.

• Avoid long edge labels.

• Avoid too many decision diamonds.

• Split architecture into separate context, container, and workflow diagrams.

• Use exported SVG for complex diagrams.

• Keep the Git source path visible near the diagram.

A good Notion documentation page usually has several small diagrams instead of one large diagram.

Example structure:

Common Diagram Types

System Context

Use for explaining who interacts with the system.

Agent Workflow

Use for LLM systems, routers, tool calling, RAG, and review loops.

Sequence Diagram

Use for API and message flows.

Sequence diagrams are less visually styleable than flowcharts, but they are often clearer for request lifecycle documentation.

Decision Tree

Use for routing logic.

AI Review Checklist

Every AI-generated diagram should be reviewed before it becomes documentation.

Use this checklist:

Common Failure Modes

The Diagram Is Too Large

Fix: split it.

Bad:

Better:

The AI Uses Unsupported Syntax

Fix: ask for conservative Mermaid syntax.

Prompt:

Styling Is Inconsistent

Fix: enforce semantic classes.

Prompt:

The Diagram Looks Correct But Is Technically False

Fix: review against implementation notes or code.

Prompt:

Notion Rendering Differs From Mermaid Chart

Fix: use Mermaid CLI exports for important diagrams.

Notion may not always match the latest Mermaid rendering behaviour. For critical documentation, store the source in Git and render an SVG yourself.

Version Control Workflow

Use pull requests for diagram changes when diagrams explain important systems.

Recommended process:

1. Create or update .mmd.

2. Render SVG.

3. Commit both source and export.

4. Review diagram diff and rendered image.

5. Update Notion page.

6. Add source path and revision notes.

Example commit:

Example pull request checklist:

Recommended Minimum Viable Setup

Do not overbuild this at the start.

Start with:

Then add rendering automation only once you have enough diagrams to justify it.

Minimum viable workflow:

1. Ask AI for a Mermaid diagram using your style guide.

2. Paste into Mermaid Chart or Mermaid Live Editor for preview.

3. Save the .mmd file in Git.

4. Paste the Mermaid code into Notion.

5. If Notion struggles, export SVG and upload that instead.

6. Keep the Git path in the Notion page.

Recommended Operating Model

Use three levels of maturity.

Level 1: Manual But Consistent

Best for getting started.

• Git stores .mmd files.

• Notion contains pasted Mermaid code.

• AI applies style guide manually.

• Mermaid editor is used for preview.

This is enough for most personal and internal documentation.

Level 2: Rendered Assets

Best for client-facing work.

• Git stores .mmd.

• Mermaid CLI renders SVG/PNG.

• Notion uses exported images for important diagrams.

• Source paths are visible in Notion.

• AI is used for updates and review.

This is the best default for consulting deliverables.

Level 3: Automated Documentation Pipeline

Best for large projects.

• CI renders all diagrams.

• Pull requests include diagram previews.

• Notion pages link to latest exports.

• AI reviews diagrams against style and implementation notes.

• Documentation freshness is tracked.

Only build this when the diagram volume justifies the maintenance cost.

Best Default For Graph/Fabrify Work

The highest-leverage setup is Level 2.

Use:

• Git for source diagrams.

• Notion for documentation pages.

• Mermaid Chart or Live Editor for quick preview.

• Mermaid CLI for client-facing exports.

• AI style guide for generation and refactoring.

Implementation Plan

This avoids unnecessary platform dependence and keeps the system portable.

Phase 1: Create The Repository

Create a small repo or folder inside an existing documentation repo:

Add:

Phase 2: Add The Style Guide

Create:

Phase 3: Create The Notion Database

Create a Diagrams database with the properties listed earlier.

Use it to track:

• What diagrams exist.

• Which project they belong to.

• Where the source lives.

• Whether they are draft, reviewed, or approved.

Phase 4: Convert Existing Diagrams

For each important existing diagram:

1. Recreate or refactor it in Mermaid.

2. Apply standard classes.

3. Save to Git.

4. Add to Notion.

5. Add a source path.

6. Mark status as draft or reviewed.

Phase 5: Add Rendering Automation

Install Mermaid CLI and render exports when needed.

Do not start with CI unless there is already a real need.

Phase 6: Add AI Review

Use the review prompt before publishing major diagrams.

For client-facing diagrams, AI review should not replace human review. It should catch syntax issues, clutter, unclear labels, and likely omissions.

Final Pattern

The repeatable pattern is:

The operating rule is:

If the diagram matters, the .mmd file lives in Git. Notion is where the diagram is explained and consumed.

This gives you a lightweight documentation system that remains editable, reviewable, portable, and AI-assisted without becoming dependent on any single visual editor.