DEV Community

Cover image for From Markdown to Mermaid Magic: Beautify Documentation with the Convert 2 Mermaid API
Marcel.L
Marcel.L

Posted on

From Markdown to Mermaid Magic: Beautify Documentation with the Convert 2 Mermaid API

#devops #mermaid #automation #diagrams

Transform Your Documentation Workflow in Seconds

If you have ever burned an evening nudging shapes inside a diagramming tool instead of shipping code, you are not alone. Teams want visual documentation because pictures explain architecture, workflows, and release plans faster than paragraphs ever could. Yet the friction is real: context switching from editor to drawing canvas, keeping versions in sync, ensuring diagrams match the latest config. What if you could describe the structure in Markdown, the language your README already speaks and instantly get a polished Mermaid diagram you can drop into docs, Confluence, or a slide deck? That is the promise of the Convert 2 Mermaid API, and it puts diagram generation back into your CI/CD pipeline where it belongs.

Let's explore how this API helps you move from text to diagram without leaving your terminal.

Why Visual Docs Matter More Than Ever

High performing teams document as they build. Architecture diagrams help new hires orient in minutes, not days. User journey maps expose weak spots in a product funnel. A simple flowchart prevents the dreaded "refresh the wiki" round trip during incident response. When diagrams fall out of date, the cost multiplies: onboarding slows, bugs slip into production, and tacit knowledge gets siloed inside senior engineers' heads.

The Convert 2 Mermaid API eliminates the choreography of manual diagramming. Because it consumes Markdown, you stay inside the tools you already love, VS Code, Neovim, even your pipeline scripts and CI/CD workflows. The output is deterministic (same input, same diagram), so you can cache responses, review diffs, and treat diagrams like code. With 14 diagram types ranging from mind maps to Git graphs, it covers everything from roadmap planning to infrastructure runbooks. In short, it makes visual documentation as repeatable as running tests.

What Makes the Convert 2 Mermaid API Special

The API focuses on developer ergonomics:

  • 14 diagram types: flowchart, mindmap, sequence, state, ER, Gantt, Git graph, user journey, class, C4, pie, Sankey, timeline, and quadrant. No matter which storytelling format you prefer, it is a single POST away.
  • Multiple output formats: request JSON (default) for programmatic use, plain text (txt) when you want copy-paste-ready Mermaid code, or rendered svg for immediate embedding. Need persistent artifacts? Set export: true and the API replies with a downloadable file complete with timestamped filename.
  • RapidAPI integration: authentication runs through familiar headers—X-RapidAPI-Key and X-RapidAPI-Host. You can plug the service into any platform that already knows how to call RapidAPI endpoints.
  • Improved SVG rendering: Base64 encoding for crisper exports, which means diagrams look sharp across browsers and PDF generators.
  • Deterministic output: because the transformation is pure, you can hash responses, store them in S3 or Redis, and skip regeneration until the Markdown changes.

Combine those traits with sub second response times and you get an API designed to slot into developer workflows without friction.

Quick Start Guide 🚀

Let us turn a simple Markdown outline into a flowchart. All you need is requests, your RapidAPI key, and a few lines of code.

import requests

url = "https://convert2mermaid.p.rapidapi.com/convert"
headers = {
    "X-RapidAPI-Key": "<YOUR_RAPIDAPI_KEY>",
    "X-RapidAPI-Host": "convert2mermaid.p.rapidapi.com",
    "Content-Type": "application/json"
}

payload = {
    "markdown": "# Incident Response\n- Detect alert\n- Triage\n- Mitigate\n- Postmortem"
}

response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
print(response.json()["mermaid"])
Enter fullscreen mode Exit fullscreen mode

Sample Response 

{
  "mermaid": "flowchart TD;\nN0[\"Incident Response\"];\nN1[\"Detect alert\"];\nN2[\"Triage\"];\nN3[\"Mitigate\"];\nN4[\"Postmortem\"];\nN0-->N1;\nN1-->N2;\nN2-->N3;\nN3-->N4;"
}
Enter fullscreen mode Exit fullscreen mode

Drop the output into Mermaid Live Editor to preview, or render it inside your Markdown docs using built-in Mermaid support (GitHub, GitLab, and many knowledge bases support it out of the box). Under the hood, the API derived node IDs, connected the steps sequentially, and preserved your headings for clarity.

Real-World Use Cases That Deliver Immediate Wins

1. README Automation

Your repository already contains installation steps in Markdown. Wrap them in a CI job that calls the API, commits the resulting flowchart, and your README will always include an up-to-date install diagram. Reviewers can diff the .mmd file just like code.

2. Sprint Planning Mind Maps

Product leads can outline epics in Markdown and convert them into mind maps for planning meetings. Because the API's mindmap output structures data radially, stakeholders grasp scope at a glance without opening yet another whiteboard link.

3. Microservice Architecture Snapshots

Use the C4 diagram type to describe systems and dependencies. Include it in your deployment pipeline so every merge to main regenerates the architecture overview. Onboarding engineers and auditors will thank you.

4. Project Timelines and Gantt Charts

Program managers can feed milestone lists into the Gantt diagram type, export an SVG, and embed it in weekly updates. No more wrestling with bespoke PM software when priorities shift.

These are just a subset of the 14 types available, mix and match to fit your storytelling needs.

Pro Implementation: Build a Diagram Pipeline

Here is how you might wire the API into a docs pipeline that generates SVGs during CI and pushes them to a docs/diagrams directory. The script scans a diagrams/ folder for Markdown stubs and caches responses to avoid unnecessary API calls.

import hashlib
import json
import os
from pathlib import Path

import requests

API_URL = "https://convert2mermaid.p.rapidapi.com/convert"
HEADERS = {
    "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    "X-RapidAPI-Host": "convert2mermaid.p.rapidapi.com",
    "Content-Type": "application/json"
}

SOURCE_DIR = Path("diagrams")
OUTPUT_DIR = Path("docs/diagrams")
CACHE_DIR = Path(".diagram-cache")

OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
CACHE_DIR.mkdir(parents=True, exist_ok=True)

for stub in SOURCE_DIR.glob("*.json"):
    payload = json.loads(stub.read_text())
    cache_key = hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()
    cache_file = CACHE_DIR / f"{cache_key}.svg"

    if cache_file.exists():
        svg = cache_file.read_text()
    else:
        response = requests.post(API_URL, json={**payload, "output_format": "svg"}, headers=HEADERS)
        response.raise_for_status()
        svg = response.text
        cache_file.write_text(svg)

    output_path = OUTPUT_DIR / f"{stub.stem}.svg"
    output_path.write_text(svg)
    print(f"Rendered {stub.name} -> {output_path.relative_to(Path.cwd())}")
Enter fullscreen mode Exit fullscreen mode

Drop JSON payloads like service-map.json (containing markdown, diagram, and optional export flags) into diagrams/, and this script will produce deterministic SVGs ready for publication. Because caching keys off the payload hash, unchanged diagrams skip network calls, perfect for monorepos where pipelines must stay lean.

Diagram Gallery: Every Mermaid Type at a Glance

1. Flowchart

Flowchart diagram preview

{
  "markdown": "# Deployment Pipeline\n- Build\n- Test\n- Security scan\n- Deploy",
  "diagram": "flowchart"
}
Enter fullscreen mode Exit fullscreen mode

2. Mindmap

Mindmap diagram preview

{
  "markdown": "# Platform Roadmap\n- Observability\n- Reliability\n- Developer experience\n- Cost optimisation",
  "diagram": "mindmap"
}
Enter fullscreen mode Exit fullscreen mode

3. Sequence

Sequence diagram preview

{
  "markdown": "# Login Flow\n- User->API: request token\n- API->Database: validate credentials\n- Database->API: success\n- API->User: token",
  "diagram": "sequence"
}
Enter fullscreen mode Exit fullscreen mode

4. State

State diagram preview

{
  "markdown": "# Order States\n- Pending\n- Confirmed\n- Shipped\n- Delivered",
  "diagram": "state"
}
Enter fullscreen mode Exit fullscreen mode

5. Entity relationship

Entity relationship diagram preview

{
  "markdown": "# E-Commerce Schema\n- Customer\n- Order\n- Product\n- Customer ||--o{ Order : places\n- Order }|--|{ Product : contains",
  "diagram": "er"
}
Enter fullscreen mode Exit fullscreen mode

6. Gantt

Gantt diagram preview

{
  "markdown": "# Release Plan\n- Phase 1:\n- Design\n- Planning\n- Phase 2:\n- Implementation\n- Testing",
  "diagram": "gantt"
}
Enter fullscreen mode Exit fullscreen mode

7. Git graph

Git graph diagram preview

{
  "markdown": "# Git History\n- commit: Initial commit\n- branch develop\n- checkout develop\n- commit: Add feature\n- checkout main\n- merge develop",
  "diagram": "git"
}
Enter fullscreen mode Exit fullscreen mode

8. User journey

User journey diagram preview

{
  "markdown": "# Shopping Experience\n- Browse products: 5: Customer\n- Add to cart: 4: Customer\n- Checkout: 3: Customer, System\n- Payment: 2: Customer, Payment gateway\n- Confirmation: 5: Customer",
  "diagram": "journey"
}
Enter fullscreen mode Exit fullscreen mode

9. Class

Class diagram preview

{
  "markdown": "# Payment Classes\n- Payment : +amount\n- Payment : +process()\n- CreditCard\n- PayPal\n- CreditCard <|-- Payment\n- PayPal <|-- Payment",
  "diagram": "class"
}
Enter fullscreen mode Exit fullscreen mode

10. C4 context

No C4 diagram available

{
  "markdown": "# System Context\n- User: Customer\n- Frontend: Web application\n- Backend: API service\n- Database: PostgreSQL",
  "diagram": "c4"
}
Enter fullscreen mode Exit fullscreen mode

11. Pie

Pie diagram preview

{
  "markdown": "# Market Share\n- Product A : 45\n- Product B : 30\n- Product C : 15\n- Product D : 10",
  "diagram": "pie"
}
Enter fullscreen mode Exit fullscreen mode

12. Sankey

Sankey diagram preview

{
  "markdown": "# Energy Flow\n- Solar,Battery,50\n- Solar,Grid,30\n- Battery,Home,40\n- Grid,Home,60",
  "diagram": "sankey"
}
Enter fullscreen mode Exit fullscreen mode

13. Timeline

Timeline diagram preview

{
  "markdown": "# Company History\n- 2010 : Company founded\n- 2015 : Series A funding\n- 2018 : Reached one million users\n- 2020 : IPO\n- 2023 : Global expansion",
  "diagram": "timeline"
}
Enter fullscreen mode Exit fullscreen mode

14. Quadrant

Quadrant diagram preview

{
  "markdown": "# Priority Matrix\n- High impact: [0.9, 0.8]\n- Quick wins: [0.7, 0.6]\n- Nice to have: [0.4, 0.3]\n- Deprioritise: [0.2, 0.5]",
  "diagram": "quadrant"
}
Enter fullscreen mode Exit fullscreen mode

Code Examples for Everyday Scenarios

Python Flowchart (covered above)

Already seen the basics? Let us expand with a mind map and an SVG export to round things out.

Node.js Mind Map for Project Planning 

const axios = require("axios");

async function generateMindMap() {
  const response = await axios.post(
    "https://convert2mermaid.p.rapidapi.com/convert",
    {
      markdown: "# Platform Roadmap\n- Observability\n- Reliability\n- Developer Experience\n- Cost Optimisation",
      diagram: "mindmap"
    },
    {
      headers: {
        "X-RapidAPI-Key": process.env.RAPIDAPI_KEY,
        "X-RapidAPI-Host": "convert2mermaid.p.rapidapi.com",
        "Content-Type": "application/json"
      }
    }
  );

  console.log(response.data.mermaid);
}

generateMindMap().catch(console.error);
Enter fullscreen mode Exit fullscreen mode

Run the snippet, paste the output into the Mermaid Live Editor, and you have a beautiful planning artifact ready for the next sprint review.

Advanced SVG Export with File Download 

import requests

url = "https://convert2mermaid.p.rapidapi.com/convert"
headers = {
    "X-RapidAPI-Key": "<YOUR_RAPIDAPI_KEY>",
    "X-RapidAPI-Host": "convert2mermaid.p.rapidapi.com",
    "Content-Type": "application/json"
}

payload = {
    "markdown": "# Deployment Pipeline\n- Build\n- Test\n- Security scan\n- Deploy\n- Monitor",
    "diagram": "flowchart",
    "output_format": "svg",
    "export": True
}

response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()

filename = "diagram.svg"
if "content-disposition" in response.headers:
    header_value = response.headers["content-disposition"]
    if "filename=" in header_value:
        filename = header_value.split("filename=")[1].strip('"')

with open(filename, "w", encoding="utf-8") as fh:
    fh.write(response.text)

print(f"Saved SVG diagram to {filename}")
Enter fullscreen mode Exit fullscreen mode

The export flag triggers a Content-Disposition header like diagram-flowchart-20251006-120045.svg, mirroring how browsers handle file downloads. You now have a production-ready graphic you can drop into SharePoint, Notion, or static sites.

Best Practices to Keep Your Diagrams Fresh 💡

  • Cache aggressively: deterministic output means you can store responses keyed by a hash of the Markdown payload. This reduces RapidAPI calls and keeps within the free tier (100 requests/month) while providing instant re-renders during local previews.
  • Pick the right format: use JSON when automation layers (like Next.js or Sphinx) will post process the output, txt for quick edits, and svg when visuals go straight into slide decks or PDFs.
  • Stay under rate limits: the free tier is perfect for small teams. For pipelines, throttle requests or batch diagram generation to avoid bursts.
  • Validate Markdown input: since whitespace matters, add linting rules (e.g., remark plugins) to ensure outlines follow the structure you expect.

Conclusion and Next Steps

The Convert 2 Mermaid API is the missing link between the documentation you intend to write and the visuals stakeholders crave. By letting you stay in Markdown, it removes hours of manual fiddling and keeps diagrams in lockstep with your repositories, playbooks, and retrospectives. You have seen how easy it is to generate flowcharts, mind maps, and SVG exports with just a few lines of code; now it is your turn to automate the diagrams lurking in TODO comments.

🚀 Try the API today: the free tier gives you 100 calls each month, enough to wire it into your README or sprint planning workflow immediately.

💡 Share what you build: post your favourite Mermaid diagrams, templates, or pipeline tips so the community can borrow ideas.

🔁 Integrate it everywhere: drop the scripts into your CI/CD pipeline, documentation generator, or knowledge base to keep architecture diagrams evergreen.

Let me know how you use the Convert 2 Mermaid.

Author

pwd9000 image

Marcel.L

Dual Microsoft MVP DevOps + Azure | DevOps Architect | Technical speaker focused on Microsoft technologies, IaC and automation in Azure. Find me on GitHub: https://github.com/Pwd9000-ML

Like, share, follow me on: 🐙 GitHub | 🐧 X/Twitter | 👾 LinkedIn

Date: 06/10/2025

Top comments (1)

Collapse
 
richmirks profile image
Richard Mirks •

14 diagram types and SVG export—whiteboards may seek early retirement.