{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreibyuoqfz7haq5w3b4egfsulprjnlhgqfcb2cv5os5glzootp6fbz4",
    "uri": "at://did:plc:j4nmy4ymoeorm3j6hzbijapg/app.bsky.feed.post/3mdkrnmhiqk22"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreifyi2iu2tsvtdizepsag37slieuvmfjrmd36x5p7iepwp4w7gilhq"
    },
    "mimeType": "image/jpeg",
    "size": 588468
  },
  "description": "Mermaid turns structured text into diagrams, and back again. A practical look at text-first diagramming, and why it works well with language models.",
  "path": "/from-text-to-diagrams-working-with-mermaid/",
  "publishedAt": "2026-01-29T12:21:55.000Z",
  "site": "https://hoeijmakers.net",
  "tags": [
    "Markdown",
    "MermaidCreate diagrams and visualizations using text and code.Try Editor",
    "From Ideas to Precision: Why I Use Mermaid with LLMs",
    "GPT Image 2 Changed My Mind on AI Visuals"
  ],
  "textContent": "There is something interesting about turning text into diagrams.\n\nNot illustrations, but diagrams that express structure: flows, dependencies, sequences. This becomes especially noticeable when the text itself is not prose, but something closer to a script. Ordered sentences that describe relations rather than tell a story.\n\nThat is roughly the space where Mermaid sits.\n\n## Text as structure, not as explanation\n\nMermaid is usually introduced as a way to generate diagrams from text. That description is accurate, but incomplete.\n\nWhat matters more is that the text is the primary artefact. You are not drawing shapes. You are describing relationships. The diagram is a rendering of that description, not the other way around.\n\nBecause of that, the process is reversible. You can always go back to the text, adjust it, and regenerate the diagram. Nothing is lost in translation.\n\nThis is different from most visual diagramming tools, where structure slowly dissolves into manual layout decisions. Once you start dragging boxes around, the model lives in your head rather than in the artefact. Mermaid keeps the structure explicit.\n\n💡\n\n****What is Mermaid?****\nMermaid is an open-source, text-based diagramming language created around 2014 by ****Knut Sveidqvist****. It allows you to describe diagrams such as flows, sequences, and state machines using plain text, which can then be rendered into visual diagrams. Mermaid is not a formal standard governed by a standards body, but it has become a widely adopted de facto standard in documentation and developer tooling, much like Markdown. Its focus is on expressing structure rather than visual design, which makes diagrams easy to edit, version, and regenerate. This text-first approach is also why Mermaid works particularly well with modern language models, which can read, generate, and modify Mermaid syntax directly.\n\n## Low resolution, by design\n\nI tend to think of Mermaid in the same category as Markdown.\n\nBoth are intentionally low-resolution formats. They do not try to look good. They try to stay readable, portable, and precise. You can open them in any editor, version them, diff them, or move them between systems without friction.\n\nThat constraint is not a drawback. It is what makes them durable.\n\nThe result is usually good enough visually, but strong in terms of meaning. For thinking, that trade-off is often exactly right.\n\n## What changes with language models\n\nWhat makes Mermaid more relevant now than it used to be is that large language models understand it natively.\n\nThey can generate Mermaid diagrams from descriptions, modify existing ones, or explain what a diagram represents. That lowers the threshold for working with structured diagrams, especially when you are still figuring things out.\n\nYou can start with a rough explanation, ask for a diagram, adjust the structure in natural language, and iterate. The diagram becomes part of the thinking process rather than a final documentation step.\n\nMermaid Chart GPT in ChatGPT\n\n## A tighter feedback loop\n\nIf you connect Mermaid generation into your workflow, for example via an MCP setup or similar tooling, that loop tightens further.\n\nYou explain something.\nYou get a diagram.\nYou adjust the structure.\nYou regenerate.\n\nNo redrawing. No exporting. No loss of intent.\n\nThis is particularly useful for architecture sketches, process descriptions, or system overviews that are still in flux.\n\nMermaid integration into Claude\n\n## Why it works for me\n\nMermaid is not a general-purpose diagramming tool, and it does not try to be one. It assumes that structure matters more than appearance, and that text is a reasonable place to express that structure.\n\nIf you are already comfortable working in Markdown, Mermaid tends to feel familiar rather than foreign.\n\nAnd if you combine it with a language model, it becomes a practical way to move back and forth between explanation, structure, and visualisation with very little overhead.\n\nNot a revolution. Just a tool that fits well with text-first ways of thinking.\n\n* * *\n\nI personally have a paid plan for this service:\n\nMermaidCreate diagrams and visualizations using text and code.Try Editor\n\nHet is a flowchart example. Textual script on the left, graphical output on the right.\n\n### Further reading\n\n  * From Ideas to Precision: Why I Use Mermaid with LLMs\n  * GPT Image 2 Changed My Mind on AI Visuals\n\n",
  "title": "From text to diagrams: working with Mermaid",
  "updatedAt": "2026-05-10T08:53:38.324Z"
}