For readable, consistent Mermaid flowcharts in Obsidian on Mac, define reusable node styles inside each diagram. Keep your app theme, check which renderer your installed version uses, and add diagram-scoped CSS only when you need shared defaults.

This walkthrough creates a small flowchart with consistent node fills, readable labels, and one clearly marked alternate step. All labels are synthetic. The goal is a reusable styling pattern for ordinary notes, with separate instructions where Mermaid and Obsidian’s newer Pele renderer behave differently.

Check your installed renderer before choosing settings

Find your build under Settings → About → App → Current version, the location documented in Obsidian’s Early access versions help. Record that version before troubleshooting styles.

There is a significant boundary: the October 22, 2026 release notes for Obsidian 1.15.0 Desktop, marked Early access, introduce Pele for rendering Mermaid diagrams. The notes say it supports Mermaid 12.1.0 syntax, uses theme colors and fonts, and produces different SVG classes. Those release notes describe that particular release; they do not establish which renderer your Mac has installed. See Obsidian 1.15.0 Desktop.

Use this decision table before copying configuration from another tutorial:

Your rendering environment Start with Boundary to remember
Obsidian using Mermaid itself Source-level flowchart classes; optionally diagram frontmatter Configuration features depend on the installed Mermaid version.
Obsidian using Pele Source-level styles; optionally Pele CSS variables Mermaid themes and themeVariables colors do not apply.
A plugin that replaces diagram rendering The plugin’s documented renderer and settings The built-in renderer’s behavior is not enough to establish compatibility.

Pele explicitly documents its own layout and appearance, even when it accepts Mermaid syntax. Its Compatibility documentation also states that configuration support varies by diagram type. Treat syntax compatibility and identical visual output as separate questions.

Build a reusable flowchart style inside the note

Create a new note and paste the complete block below, including its opening and closing fences. Obsidian’s Advanced formatting syntax documentation specifies a fenced code block labeled mermaid for diagrams.

```mermaid
flowchart TD
    A[Item A] --> B[Step B]
    B --> C[Result C]
    B --> D[Option D]

    classDef standard fill:#edf2f7,stroke:#475569,color:#172033,stroke-width:2px;
    classDef alternate fill:#e0f2fe,stroke:#0369a1,color:#172033,stroke-width:2px;
    class A,B,C standard;
    class D alternate;
```

Mermaid’s documented classDef syntax defines a reusable appearance; class assigns it to named nodes. Here, three nodes share standard, and one uses alternate. Keep node identifiers separate from visible labels so wording changes are easy to follow. These mechanisms are described in Flowcharts — Basic Syntax.

The palette is an illustrative design choice. It pairs pale fills with dark text and stronger borders. The label Option D also identifies the alternate step, so its meaning does not depend solely on a blue fill.

Preview the note and check the labels at your usual reading size. The intended result is three matching gray nodes and one blue node. Leave the arrows at their renderer defaults initially; this makes it easier to judge one change at a time.

To reuse the pattern, copy the entire block into another note, change the labels and connections, and update the node lists in the final two lines. Keep one reference copy of the palette. This is a manual convention: editing the reference does not automatically update diagrams already copied elsewhere.

Pele also supports diagram-defined styling, and its documentation explains that source-defined colors remain fixed when the theme changes. That makes this approach useful when you want a consistent palette while retaining your Obsidian theme. See Pele Theming.

Use diagram frontmatter only when Mermaid renders the diagram

If your installed environment uses Mermaid itself and supports diagram frontmatter, you can set a diagram’s overall palette and typography together. Mermaid documents frontmatter configuration from version 10.5.0 onward. Its site-level initialization belongs to the integrating application; a note author can use diagram-local configuration instead. See Mermaid Configuration.

This complete alternative sets a shared appearance for all three nodes. Use it in a separate test block first:

```mermaid
---
config:
  theme: base
  themeVariables:
    primaryColor: "#edf2f7"
    primaryTextColor: "#172033"
    primaryBorderColor: "#475569"
    lineColor: "#64748b"
    fontFamily: "Arial, sans-serif"
    fontSize: "16px"
---
flowchart TD
    A[Item A] --> B[Step B]
    B --> C[Result C]
```

The YAML belongs inside the mermaid fence, before flowchart TD. It is diagram configuration, separate from the note’s properties at the top of a Markdown file.

Mermaid specifies base as the customizable theme and requires hexadecimal colors for its theming engine. Its Theme Configuration documentation lists the text, fill, border, line, and font variables used above. These settings describe the diagram’s appearance without selecting a different Obsidian app theme.

On Pele, changing this example’s themeVariables colors will not produce the same result: those colors are explicitly unsupported. Use source-defined classes for fixed node colors, or the CSS-variable approach below for shared renderer defaults. Do not interpret ignored Mermaid theme settings as a reason to keep adjusting hexadecimal values. See Pele Compatibility.

Add shared Pele defaults with a small CSS snippet

For a Pele-based installation, CSS variables offer another supported route. This is useful when several diagrams should share defaults and you prefer changing one stylesheet over editing every block.

The following complete snippet targets Pele flowcharts. It sets text, fills, borders, and connector colors while leaving the surrounding note and application theme alone. The selector and variables are documented in Pele Theming.

.pele-flowchart {
  --pele-bg: #ffffff;
  --pele-fg: #172033;
  --pele-line: #64748b;
  --pele-surface: #edf2f7;
  --pele-surface-alt: #e2e8f0;
  --pele-border: #475569;
}

Install it through Obsidian’s documented desktop workflow:

  1. Open Settings.
  2. Under Appearance → CSS snippets, select Open snippets folder.
  3. Create a plain-text file named diagram-defaults.css in that folder and paste the CSS into it.
  4. Return to Appearance → CSS snippets and select Reload snippets.
  5. Enable diagram-defaults.

These controls and the automatic application of saved snippet changes are documented in CSS snippets — Obsidian Help. On Mac, check that your editor saved the filename with the .css extension.

Test the shared defaults using the three-node diagram from the previous section, removing its diagram frontmatter. Source-defined colors can override renderer defaults, so the first example’s explicit node classes are unsuitable for judging whether the shared fill variables took effect.

This snippet deliberately uses a fixed light palette. If your preferred reading setup needs a different palette, change the text, surfaces, borders, and lines together, then inspect the result. The --pele-bg variable serves background elements; it does not promise an opaque panel behind the entire diagram.

Keep this snippet specific to Pele. Mermaid’s own flowchart documentation recommends classDef for node styling and warns that external CSS can lose to Mermaid’s internal styles. A stylesheet targeting one renderer should not be assumed to work with the other. See Mermaid’s CSS classes guidance.

Diagnose unreadable diagrams in a repeatable order

Use the following sequence when a diagram renders but its appearance is inconsistent. It separates syntax, styling scope, and available space without changing your app theme.

  1. Reduce the test. Copy the note’s diagram into a temporary note and keep three short labels. If the small example fails too, investigate syntax or renderer support before refining colors.
  2. Choose one styling mechanism. Test source classes alone, Mermaid frontmatter alone, or Pele variables alone. Combining them immediately makes overrides harder to identify.
  3. Check paired colors. Inspect text against its node fill, then borders and arrows against the surrounding note. Fix the unreadable pair before adding another accent.
  4. Check the reading width. Preview the diagram in the pane width you normally use. Shorten labels or try a vertical arrangement if the chart becomes too wide.
  5. Reintroduce complexity gradually. Add the remaining nodes, alternate styles, and edge labels in small groups. Keep the last readable version available for comparison.

For the direction check, Mermaid documents TD as top to bottom and LR as left to right. Try changing only that declaration before rewriting the diagram. See Flowchart direction.

Judge the final result in your installed Obsidian renderer. An external editor can help examine syntax, but Pele documents different node positions, spacing, and edge paths from Mermaid. Matching source does not require matching geometry.

Keep a small reference diagram alongside your reusable palette. Once its labels, nodes, and connectors read clearly at your normal pane width, apply the same convention to your working notes. Consistency comes from a repeatable style and a known renderer boundary; your Obsidian theme can stay as it is.

Sources