I could have built a standalone Wardley Map library. Or a VSCode extension. Or yet another web app.
I chose to contribute to Mermaid instead. Here’s why.
GitHub Native
Mermaid is built into GitHub markdown rendering. Write a fenced code block with mermaid, and it just renders. No extensions. No build steps. No external services.
```mermaid
flowchart LR
A[Start] --> B[End]
That's the dream: strategic diagrams that live in your README, your ADRs, your planning docs. Version controlled. Diffable. Reviewable in PRs.
GitHub [added native Mermaid support in 2022](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/). It was a big deal. Millions of developers can now embed diagrams without any tooling setup.
I want Wardley Maps to have that same zero-friction experience.
## Open Standards
Mermaid is open source, MIT licensed, with a massive community:
- 70k+ GitHub stars
- 1,000+ contributors
- Active maintenance and releases
It's not going anywhere. My Wardley Map syntax won't be locked into some proprietary tool that pivots, gets acquired, or shuts down. The code is there. The community is there.
If Mermaid disappeared tomorrow (it won't), someone could fork it and keep going. That's the power of open source.
## Modern Architecture
The Mermaid team has been migrating to [Langium](https://langium.org/) for diagram grammars. This is the right technical foundation:
- **Declarative grammar definitions**: Define syntax in `.langium` files, not imperative parsing code
- **Type-safe AST**: TypeScript types generated from the grammar
- **Clean separation**: Grammar → Parser → AST → Database → Renderer
- **Better tooling**: LSP support, syntax highlighting, validation
The older Jison-based parsers worked, but Langium is the future. I built Wardley Maps on the modern stack from day one.
## The Ecosystem
Once Wardley Maps land in Mermaid, they work everywhere Mermaid works:
| Platform | Support |
|----------|---------|
| GitHub | Native rendering in markdown |
| GitLab | Native rendering in markdown |
| Notion | Via embed blocks |
| Obsidian | Native plugin |
| VS Code | Preview extensions |
| Docusaurus | Built-in support |
| Confluence | Via plugins |
| Slack | Via unfurling |
One contribution, massive reach. That's leverage.
## The Alternative Was Worse
I considered the alternatives:
**Build a standalone library**: I'd have to convince every platform to integrate it separately. Years of work, fragmented adoption.
**Build a VS Code extension**: Great for VS Code users, useless everywhere else.
**Build a web app**: Another tool to context-switch to. Another place for diagrams to get stale.
Contributing to Mermaid means I do the work once, and the ecosystem does the distribution.
## Open Source Strategy
There's a meta-lesson here about building in public:
1. **Find where the users already are** (Mermaid has massive adoption)
2. **Build on modern foundations** (Langium, not legacy Jison)
3. **Contribute upstream** (don't fork unless you have to)
4. **Design for the ecosystem** (GitHub, GitLab, Notion, etc.)
This is how you get leverage on your time. Next: actually building the thing.
