Diagram help
Lightweight reference for Mermaid and SVG diagram rendering gotchas. Use when choosing between Mermaid, Mermaid-rendered SVG, and direct SVG, or when producing diagrams that must render reliably through mmdc, rsvg-convert, PNG, or PowerPoint. Keywords: diagram, mermaid, mmdc, SVG, rsvg, PowerPoint, rendering, portability.From its SKILL.md
npx -y skills add jmerkow/my-agentic-stuff --skill diagram-helpAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
2.9 KB, as published. Nobody here has run it
Diagram Help
This is a small reference skill, not a diagram workflow. Use it for the handful of diagram facts that are easy to forget and expensive to debug.
Decision
- Use Mermaid for structured diagrams that fit Mermaid's model: flowcharts, sequence diagrams, state machines, class diagrams, ER diagrams, and simple timelines.
- Use Mermaid to SVG when Mermaid mostly gets the structure right but the final visual needs manual polish. Render with
mmdc, then edit the SVG. - Use direct SVG when layout, spacing, shapes, or visual hierarchy matter more than Mermaid's automatic layout.
Things Worth Remembering
1. Mermaid can become SVG
mmdc -i diagram.mmd -o diagram.svg -w 1920 -H 1080
mmdc -i diagram.mmd -o diagram.png -w 1920 -H 1080 -s 2
Use -s 2 for PNGs that need to stay crisp when downscaled into slides or docs.
2. Standalone SVG needs inline style
rsvg-convert and PowerPoint do not reliably load external CSS or honor <?xml-stylesheet?>. Put the <style> block inside the SVG.
<style type="text/css"><![CDATA[
.bg { fill: #ffffff; }
.text { fill: #1a1a1a; font-family: -apple-system, 'Segoe UI', Helvetica, Arial, sans-serif; }
.accent-stroke { stroke: #0078d4; fill: none; }
]]></style>
3. Paint the background with a rect
svg { background-color: ... } is ignored by rsvg-convert and PowerPoint. Add an explicit background rectangle after the style block.
<rect x="0" y="0" width="1920" height="1080" class="bg" />
4. Use system fonts for render fidelity
rsvg-convert resolves fonts through fontconfig on the render host. If a named font is missing, fallback glyph metrics can change wrapping, overflow labels, or collide with positioned shapes.
Use:
-apple-system, 'Segoe UI', Helvetica, Arial, sans-serif
Avoid Google Fonts, @import, and distinctive display faces unless the rendering environment is known to have them.
5. Avoid renderer-sensitive SVG tricks
- Avoid
currentColorfor chained fills; it works in browsers but is inconsistent inrsvg-convertand PowerPoint. - Avoid scattered
fill="#xxx"andstroke="#xxx"if you expect to retheme the SVG. Prefer classes. - Avoid external assets unless the output path is known to preserve them.
6. Two tiny layout snippets
Hub-and-spoke placement:
x = cx + r * cos((2 * pi / N) * i)
y = cy + r * sin((2 * pi / N) * i)
Visible self-loop in direct SVG:
<path d="M 335 160 C 310 95 440 95 415 160" class="accent-stroke" />
These are snippets, not rules. Adjust coordinates to the actual viewBox and label lengths.