Interactive Mermaid Diagrams Integration Guide

Introduction

In modern technical documentation and web publishing, a picture is worth a thousand lines of text. Visualizing complex workflows, system architectures, and lifecycle states helps readers digest technical details rapidly.

Rather than relying on heavy, non-searchable static image files or slow third-party CDNs that increase page latency and degrade privacy, PolyCMS integrates a native Self-Hosted Mermaid.js rendering pipeline. This guide covers how diagrams are compiled dynamically, introduces the interactive visual TipTap editor element, and demonstrates four chart examples ranging from simple flows to the overall architecture of PolyCMS.

Technical Architecture & Self-Hosted Strategy

PolyCMS is built for speed and absolute sovereignty. The core renderer parses raw block elements dynamically. When a block is marked as a diagram:

1. Parser Detection: The PHP dynamic engine (helpers.php) scans for standard Markdown blocks starting with <pre><code class="language-mermaid">.
2. Safe Entity Decoding: It decodes HTML entities safely (e.g. converting --> back to the raw parser-ready --> syntax).
3. Offline Assets: Instead of requesting jsDelivr or cdnjs, PolyCMS resolves the script locally via the Laravel asset('assets/vendor/mermaid-10.x/mermaid.min.js') helper.
4. Vercel-Inspired Theme Variables: Both the admin visual editor and public frontend render the diagrams with custom Vercel-like base variables, delivering high-contrast, clean minimalist aesthetics in both Light and Dark modes.

Diagram Presets & Examples

Below are four classic diagram implementations running natively in PolyCMS.

1. Simple Flowchart: User Authentication Lifecycle (Horizontal - LR)

A simple left-to-right flow chart displaying how standard client-side inputs are parsed and authenticated by the session guard.

2. State Diagram: E-Commerce Transaction Lifecycle (StateDiagram-v2)

A state diagram depicting the possible state transitions of an online purchase transaction through PayPal or SePay payment gateways.

3. Intermediate Sequence Diagram: Secure REST API Request Flow

A sequence diagram showcasing the secure back-and-forth interactions between a Customer, the Web Client, the API Gateway, and the Database to serve token-authenticated content.

PolyCMS Core Architectural Workflow (Complex - TD)

To demonstrate a complex vertical layout, here is the complete technical architectural pipeline of PolyCMS. It outlines how a post travels from the Database, passes through the dynamic block compiler, parses the shortcode/Mermaid tags, applies WordPress-inspired hook/filter hooks, and finally outputs premium Vercel-styled HTML views.

Interactive TipTap Diagram Block Editor

As an author in the PolyCMS Admin Panel, you do not need to memorise Mermaid syntax to create these beautiful graphics. In the block editor:

1. Click the Mermaid Diagram button on the editor toolbar.
2. An elegant visual container will instantly render inline.
3. Switch to the Edit Code tab to write syntax with helper buttons (--> Arrow, [Node], {Decision}).
4. Use the Templates dropdown to instantly load standard presets (Flowcharts, Sequences, States) and modify them on the fly.
5. If your syntax is incorrect, the built-in compiler highlights the line and shows a helpful error banner without interrupting your drafting process!