blog.dopana

Back

You embed a few architecture diagrams into your blog posts using ````mermaid` blocks. When readers open the page, the article text appears immediately, but the diagram areas remain blank placeholders. A few seconds later, after the browser finishes downloading and executing megabytes of library code, the page violently jerks downwards (Cumulative Layout Shift) as the diagrams finally pop into view.

This jarring delay is typical when using client-side Mermaid rendering libraries like astro-mermaid. In this guide, we walk through replacing astro-mermaid entirely with Pele — a lightweight Mermaid compiler that turns diagrams into pure, themeable SVGs during static site generation (SSG), saving 100% of client-side diagram JavaScript.

The Problem: Client-Side Mermaid Overhead#

The standard astro-mermaid integration relies on a browser-side lifecycle:

  1. At build time: Astro converts Markdown ````mermaidblocks into plain
    ` HTML elements.
  2. At page load: The browser fetches the full mermaid.js bundle (2MB to 3MB uncompressed).
  3. Execution: The client CPU runs complex layout engines (Dagre, Elk, D3) to parse the syntax and paint SVG elements into the DOM.
  4. Theme switching: Toggling between light and dark modes forces JavaScript to re-parse and redraw every diagram on the page from scratch.
New Way: remark-peleOld Way: astro-mermaidMarkdown (.md)Astro BuildHTML with pre.mermaidBrowser loads pageDownload mermaid.js bundle(~2-3MB)Client JS calculates layout andrenders SVG(Layout shifts, CPU spikes,slow)Markdown (.md)Astro Build + PeleHTML with baked-in SVGBrowser displays diagraminstantly(0KB JS, Zero layout shifts)

[!WARNING] If a reader has JavaScript disabled, uses a privacy extension that blocks heavy scripts, or suffers from high latency, client-side diagrams fail completely, leaving behind raw code blocks.

What is Pele? (Explain Like I’m 10)#

Think of it like buying a dinner table:

  • Client-side Mermaid is like flat-pack furniture shipped with 100 loose screws and an instruction booklet: The customer (the reader’s browser) has to build the table before they can eat dinner.
  • Pele is like having the craftsman build and finish the solid wood table before delivering it: As soon as the package arrives, the table is completely ready to use with zero assembly required.

Pele ↗ is an open-source Mermaid renderer created by kepano (CEO of Obsidian). Key benefits include:

  • Synchronous Server-Side Rendering: Transforms Mermaid syntax into SVG directly inside Node.js or Bun without requiring a headless browser (such as Puppeteer).
  • CSS Variable Theming: Pele SVGs rely on standard CSS custom properties like --pele-bg, --pele-fg, --pele-surface, and --pele-border. Dark and light mode switches occur natively in CSS with zero runtime JavaScript.
  • Wide Syntax Compatibility: Seamlessly renders standard flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, git graphs, mindmaps, and timelines.

Step-by-Step Implementation Guide#

Step 1: Install Pele#

Add pele to your project dependencies:

bun add pele
# Or with npm: npm install pele
# Or with pnpm: pnpm add pele
bash

Step 2: Create the remark-pele.ts Plugin#

Create a new file at src/plugins/remark-pele.ts. This plugin traverses the Markdown Abstract Syntax Tree (MDAST), finds code blocks tagged with mermaid, and transforms them into inline SVG markup:

[!TIP] Setting idPrefix: pele-${diagramIndex}- ensures that arrow markers, gradients, and clip paths inside SVGs remain unique across the page, avoiding duplicate ID bugs when multiple diagrams exist in one article.

Step 3: Configure astro.config.ts#

Open astro.config.ts, remove the astroMermaid integration, and pass remarkPele into markdown.processor:

Step 4: Theme with CSS Variables#

Map Pele’s theme variables to your site’s existing design tokens in your global stylesheet:

Add horizontal scrolling styling for mobile responsiveness:

Step 5: Clean Up Client Scripts & Uninstall Packages#

Delete the browser initialization scripts (mermaid.run() or mermaid.initialize()) from your main layout (such as BaseLayout.astro). Then remove the obsolete dependencies:

bun remove astro-mermaid mermaid
bash

Results & Impact#

MetricBefore (astro-mermaid)After (pele)Improvement
Client JS Payload~2.5 MB (mermaid bundle)0 KB-100%
Cumulative Layout Shift (CLS)Frequent noticeable shifts0 (None)Rock Solid
No-JavaScript SupportBroken / unrendered textRenders perfectlyComplete resilience
Theme Switching DelayLaggy JavaScript redrawInstant (CSS)Fluid
Build TimeN/A845 diagrams in ~1.5sNear instantaneous

Conclusion#

Switching from client-side Mermaid rendering to build-time SVGs with Pele delivers instant page loads, eliminates cumulative layout shifts, and removes megabytes of unnecessary client JavaScript while maintaining full aesthetic control via CSS tokens.

References#