tessl/npm-docusaurus--theme-mermaid
Mermaid diagram rendering components for Docusaurus websites with theme integration and error handling
—
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
components.mddocs/
Components
Pre-built React components for rendering Mermaid diagrams with error handling and safe rendering.
Capabilities
Mermaid Component
Main React component for rendering Mermaid diagrams with built-in error boundaries.
/**
* Main React component for rendering Mermaid diagrams with built-in error boundaries
* @param props - Component props containing Mermaid diagram text
* @returns React node with rendered Mermaid diagram or error fallback
*/
function Mermaid(props: Props): ReactNode;
interface Props {
/** Mermaid diagram text content to render */
value: string;
}Usage Example:
import React from "react";
import Mermaid from "@theme/Mermaid";
export default function MyDocPage() {
const flowchartCode = `
graph TD
A[User Request] --> B{Valid Input?}
B -->|Yes| C[Process Data]
B -->|No| D[Return Error]
C --> E[Generate Response]
D --> F[Send Error Message]
E --> G[Send Response]
F --> G
`;
const sequenceCode = `
sequenceDiagram
participant Client
participant Server
participant Database
Client->>Server: API Request
Server->>Database: Query Data
Database-->>Server: Return Results
Server-->>Client: JSON Response
`;
return (
<div>
<h2>Process Flow</h2>
<Mermaid value={flowchartCode} />
<h2>API Sequence</h2>
<Mermaid value={sequenceCode} />
</div>
);
}Component Architecture
The Mermaid component uses a layered architecture for safe rendering:
Error Boundary Layer
Wraps the entire component with Docusaurus's error boundary system:
// Internal implementation structure (not directly exported)
function Mermaid(props: Props): ReactNode {
return (
<ErrorBoundary fallback={ErrorBoundaryErrorMessageFallback}>
<MermaidRenderer {...props} />
</ErrorBoundary>
);
}Rendering Layer
Handles the actual Mermaid rendering logic:
// Internal MermaidRenderer component (not directly exported)
function MermaidRenderer({ value }: Props): ReactNode;Result Display Layer
Manages SVG output and function binding:
// Internal MermaidRenderResult component (not directly exported)
function MermaidRenderResult({ renderResult }: {
renderResult: RenderResult
}): ReactNode;Styling Integration
The component automatically applies consistent styling through:
- Container Class: Uses
MermaidContainerClassNamefor stable CSS targeting - Module Styles: Includes component-specific styles from
styles.module.css - Theme Integration: Automatically adapts to Docusaurus light/dark themes
Custom Styling Example:
/* In your custom CSS */
.docusaurus-mermaid-container {
margin: 2rem 0;
text-align: center;
}
.docusaurus-mermaid-container svg {
max-width: 100%;
height: auto;
}
/* Dark theme specific styles */
[data-theme='dark'] .docusaurus-mermaid-container {
background-color: var(--ifm-background-color-subtle);
border-radius: 8px;
padding: 1rem;
}Error Handling
The component provides comprehensive error handling:
- Parse Errors: Invalid Mermaid syntax shows user-friendly error message
- Render Errors: Runtime rendering failures are caught and displayed
- DOM Cleanup: Failed render attempts are automatically cleaned up
- Fallback UI: Error boundary shows helpful error message instead of breaking the page
Error States:
- Loading State: Component returns
nullwhile rendering - Success State: Displays rendered SVG with interactive features
- Error State: Shows error boundary fallback with diagnostic information
Supported Diagram Types
The component supports all Mermaid diagram types including:
- Flowcharts:
graph TD,graph LR,flowchart - Sequence Diagrams:
sequenceDiagram - Class Diagrams:
classDiagram - State Diagrams:
stateDiagram-v2 - Entity Relationship:
erDiagram - User Journey:
journey - Gantt Charts:
gantt - Pie Charts:
pie - Git Graphs:
gitgraph - C4 Diagrams:
C4Context,C4Container,C4Component - Mindmaps:
mindmap - Timeline:
timeline
Install with Tessl CLI
npx tessl i tessl/npm-docusaurus--theme-mermaid