Mermaid diagrams are one of the most beloved communication methods among software engineers.
For those unfamiliar with Mermaid, here's an explanation from the official documentation:
Mermaid is a JavaScript-based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation keep pace with development.
Mermaid supports various diagram types, similar to PlantUML—for example, flowcharts, sequence diagrams, class diagrams, state diagrams, entity relationship diagrams, and so on.
Even though Hackers' Pub targets software engineers as its primary audience, it currently doesn't support Mermaid diagrams.
With Mermaid diagram support, software engineers can easily explain how components behave, how they communicate with each other, what problems users face, and so on—so that reviewers or readers can understand the entire workflow with ease.
Implementation plan
The naive approach would be to simply import the mermaid-js library and apply Mermaid rendering on top of the Markdown renderer. Straightforward.
But we should consider performance. Rendering every Mermaid block on a page would add considerable overhead for the browser, potentially causing memory leaks or excessive memory usage.
There are two ideas to resolve this:
- Make rendering opt-in inline. Notes should not render Mermaid diagrams by default. Rendering happens only when the user explicitly expands/unfolds the block.
- Render by default on detail pages (notes, articles). This ensures the full page is readable without extra interaction, since a detail page is a focused, single-item view rather than a feed of many items.
With these ideas combined, we can offer richer Mermaid support without sacrificing performance on list/feed views.
Possible concerns
- XSS: Mermaid rendering involves parsing user-supplied text into SVG/DOM, so we need to sanitize input carefully.
- CSS horizontal overflow that could break the layout of the surrounding page.
- Rendering performance on low-end devices.
- etc.
Mermaid diagrams are one of the most beloved communication methods among software engineers.
For those unfamiliar with Mermaid, here's an explanation from the official documentation:
Mermaid supports various diagram types, similar to PlantUML—for example, flowcharts, sequence diagrams, class diagrams, state diagrams, entity relationship diagrams, and so on.
Even though Hackers' Pub targets software engineers as its primary audience, it currently doesn't support Mermaid diagrams.
With Mermaid diagram support, software engineers can easily explain how components behave, how they communicate with each other, what problems users face, and so on—so that reviewers or readers can understand the entire workflow with ease.
Implementation plan
The naive approach would be to simply import the
mermaid-jslibrary and apply Mermaid rendering on top of the Markdown renderer. Straightforward.But we should consider performance. Rendering every Mermaid block on a page would add considerable overhead for the browser, potentially causing memory leaks or excessive memory usage.
There are two ideas to resolve this:
With these ideas combined, we can offer richer Mermaid support without sacrificing performance on list/feed views.
Possible concerns