So I wanted Wardley Maps in my workflow. Native. Version-controlled. In markdown. Living alongside my code and documentation.
The options were… limited.
What Exists Today
I spent a weekend evaluating every Wardley Map tool I could find:
-
OnlineWardleyMaps: The gold standard for web-based mapping. Great UI, good export options. But it’s a separate app—you create maps there, export images, paste them into docs. They become stale immediately. No version control. No diffs.
-
MapScript: Text-based syntax (good!), but outputs to a standalone viewer. Same problem—not embeddable where I work.
-
Draw.io / Excalidraw: Manual drawing. Every position change is a drag operation. Try keeping 20 components aligned. Try diffing changes in a PR. It doesn’t work.
-
Python libraries: Code-based generation, which I like in principle. But heavy setup for quick diagrams, and the output is still an image file you have to manage separately.
-
PowerPoint / Keynote: I’ve seen entire strategy decks built this way. Please, no.
None of these fit how I actually work.
How I Work
I live in GitHub. My planning docs are markdown. My ADRs (Architecture Decision Records) are markdown. My READMEs are markdown.
When I add a sequence diagram, I write:
sequenceDiagram
Client->>API: Request
API->>Database: Query
Database-->>API: Results
API-->>Client: Response
And it just renders. In GitHub. In my editor preview. In documentation sites. No image files. No external tools. No staleness.
This is what I wanted for strategy diagrams.
The Gap
Mermaid.js does this perfectly for:
- Flowcharts
- Sequence diagrams
- Entity relationships
- State diagrams
- Gantt charts
- Git graphs
- And many more…
But no Wardley Maps.
I checked. I searched the issues. People have asked for it. There’s been prior discussion going back years. Nothing shipped.
Why This Matters
Strategic diagrams shouldn’t be second-class citizens. If I can put a flowchart in my README and have it render natively on GitHub, I should be able to do the same with a Wardley Map.
Version-controlled strategy. Diffable decisions. Diagrams that live with the code they describe.
Imagine reviewing a PR that changes your architecture—and the strategy map updates in the same commit. That’s the workflow I want.
The Decision
If it doesn’t exist and I need it, I’ll build it.
The approach: contribute directly to Mermaid.js. Not a fork. Not a separate library. Native support that works everywhere Mermaid works.
Next up: why Mermaid was the right place to build this.
