Talk:Mermaid (software)
Add topicLatest comment: 6 months ago by Kvng in topic Requested edit: new copy + formatting (COI)
 | This article is rated Start-class on Wikipedia's content assessment scale. It is of interest to the following WikiProjects: | |||||||||||||
| ||||||||||||||
Requested edit: new copy + formatting (COI)
[edit]Disclosure: I’m work for Mermaid Chart Inc. and therefore have a COI. I’m requesting an update to clarify the distinction between Mermaid.js (the open-source library) and Mermaid Chart (the open-core company), and to improve structure with updated content + citations. Thank you in advance for reviewing, and please let me know if there's any feedback.
What changed: Replace the current lead and sections with the draft below (verbatim). The bracketed reference numbers correspond to the article’s existing references; I can supply full citation markup if helpful.
Proposed text (verbatim; please copy/paste):
Proposed text | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Mermaid.js is an open-source JavaScript library that renders diagrams from plain-text descriptions written in a Markdown-like domain-specific language (DSL).[1] It is commonly used in documentation and developer workflows where diagrams are stored, versioned, and reviewed as text alongside source code. Several platforms, including Github, render Mermaid inside Markdown.[2][3] History Mermaid.js was created in 2014 by Swedish software architect Knut Sveidqvist to keep diagrams aligned with software documentation. Sveidqvist stated that the idea emerged after losing a Microsoft Visio file, which led him to pursue a text-based, Markdown-centric approach. The project name was inspired by The Little Mermaid, which his children were watching at the time.[1][4][5][10] The project’s goal is to describe diagrams in plain text kept in version control, helping documentation keep pace with development and addressing “doc-rot.”[1] Publication The Official Guide to Mermaid.js (Packt, 2021)[12][13] by Knut Sveidqvist and Ashish Jain provides an introduction to Mermaid syntax and usage, covering diagram types such as flowcharts, sequence, class, state, ER, and Gantt diagrams, as well as theming and documentation workflows. Open core company In 2022, Sveidqvist co-founded Mermaid Chart Inc. (referred to as Mermaid) which offers hosted editing tools and enterprise features distinct from the open-source library. The company’s hosted and enterprise offerings are proprietary open-core extensions.[4][10] The commercial products focus on text-to-diagram workflows, facilitating versioning, automation, and code reviews.[14][15] The company announced a US$7.5 million seed round in March 2024. Reported investors included Open Core Ventures, Microsoft’s M12, and funds affiliated with Sequoia Capital.[5][10][16][17][18] Development The project is developed under both open-source and commercial models. The core functionality remains open-source under the MIT License.[11] Open-source tools: Mermaid diagrams can be authored and previewed without local installation using the open-source Mermaid Live Editor. The open-source Mermaid Live Editor provides a web preview and export interface.[19][25] Commercial tools: Mermaid provides a visual editor and AI-assisted features (such as text-to-diagram and file-assisted diagramming). These are a part of the Mermaid product and are distinct from the open-source Mermaid library.[6][20] Features Diagram Types Mermaid defines multiple diagram classes expressed as plain text (for example, flowcharts, sequence, class, state, and entity-relationship diagrams). Additional types have been added over time; the v11 documentation lists user-journey, Gantt, mindmap, timeline, and others.[6][7] Diagrams can be rendered client-side in the browser or generated via CLI and CI/CD workflows.[7][8] Syntax Mermaid diagrams are authored as plain text in fenced code blocks using a concise domain-specific language.[1][9] For example: Flowchart (example): flowchart TD A[Text description] --> B[Mermaid code] B --> C[Rendered diagram] C --> D[Review / version] Usage Typical use of Mermaid involves writing diagrams in plain-text Mermaid syntax, rendering them locally or on supported platforms, storing the source with documentation or code, and automating updates in CI/CD pipelines. A text-first workflow commonly includes: Author the diagram as a short text block in Mermaid syntax. [7] Render locally or on platforms that support Mermaid (for example, GitHub renders Mermaid in Markdown in issues, discussions, pull requests, wikis, and files).[2] Store and review the diagram source with related documentation or code so changes can be versioned and reviewed like other text (commonly on Git hosts).[8] Automate generation or updates in CI/CD as part of documentation or build pipelines.[8][21][22] Use with AI systems where available: editor/IDE extensions and assistant features can draft Mermaid text from natural language for subsequent human editing.[23][24] Integrations Major developer platforms document built-in Mermaid rendering, including GitHub [2][3][33], GitLab[36][37][38], and Azure DevOps wikis.[31][32] Other software forges and ALM tools (such as Gitea and Tuleap) document support in their Markdown or wiki components.[34][35] Editors and IDEs Mermaid can be authored or previewed in a number of editors through extensions or built-in support. Examples include Visual Studio Code[39][40][41], JetBrains IDEs[42], Notion[43], Obsidian[44], Joplin[45], and Quarto[46]. Several AI-assisted development tools can generate or validate Mermaid syntax, typically via editor extensions or chat-based assistants; for example, GitHub Copilot Chat[51][52] documents Mermaid diagram generation, and editors also expose Mermaid through chat participants or Model Context Protocol integrations[54]. Work management and productivity software Diagram creation and embedding are available through apps or add-ons for Atlassian Confluence[47] and Jira[48], Microsoft 365[50][51] (PowerPoint and Word), and Google Docs[49]. Additional editor and static-site integrations are listed in the project’s integrations page and vendor documentation.[30] Comparison Text-first vs. visual editors Mermaid uses a text-based DSL and renders from source text, which can be versioned and reviewed like code. CLI and API support automation and CI/CD.[8][11] diagrams.net (previously draw.io) is primarily a graphical editor (web/desktop) with diagram files stored as XML and broad app integrations (e.g., Atlassian).[26] PlantUML is another text-based system for diagram specification; it provides a different syntax and tooling approach.[27] Graphviz focuses on graph layouts (e.g., DOT language) and is widely used for pipelines and graph structures.[28] This section summarizes different diagramming approaches without implying preference. Reception Mermaid and its related tools have been discussed in developer media, particularly regarding “diagrams-as-code” workflows and platform integrations.[3][4][21][23] In 2019, Mermaid received the JavaScript Open Source Award for “The Most Exciting Use of Technology.”[29] | ||||||||||||||||||
Notes for editors: Happy to break this into smaller requests (e.g., “Integrations” only) if that’s easier to review. Scope is limited to structural/organizational clarity; no promotional language has been added. Sleepyfuecoco (talk) 20:49, 4 November 2025 (UTC)
- It is difficult to digest this as it is. It would be ideal if you could provide a machine-generated diff or at least explain what's different compared to the published version and the justification for the changes. If you don't know how to provide some sort of machine-generated diff then, yes, provide the proposed wikitext so that an editor can do the machine diff. ~Kvng (talk) 14:22, 18 November 2025 (UTC)
- Hi @Kvng, thanks so much for this feedback – super helpful, and appreciate the guidance. It's slightly long below, but wanted to provide as much context and content as possible.
diff |
|---|
|
- ================================================================
- Detailed justifications by section
- 1. Lead paragraph changes
- Rationale: More precise technical terminology ("JavaScript library" vs. "JavaScript-based tool"); clarifies text-first, version-control use case upfront
- Why: Current lead mixes definition with history; proposed lead is more focused
- Sources: Uses same existing citations [1][2][3]
- 2. New History section
- Rationale: Provides encyclopedic historical context separate from technical description
- Why: Standard Wikipedia structure; origin story is notable and well-sourced
- Sources: TechCrunch, Pulse 2.0, existing citations about founder's motivation
- Comparison: Similar software articles (React, Vue.js) have dedicated history sections
- 3. New Publication section
- Rationale: Documents notable published work about the software
- Why: Official guide is significant secondary literature; follows Wikipedia conventions
- Sources: Packt Publishing, author citations
- Comparison: Technical books are commonly documented for software articles
- 4. Open core company section (expanded from brief mention)
- Rationale: Clearly separates Mermaid.js (library) from Mermaid Chart Inc. (company)
- Why: Current article conflates the two, causing reader confusion; open-core model needs explanation
- Sources: TechCrunch funding announcement, company documentation
- Comparison: MongoDB, Elasticsearch, and other open-core projects have similar sections
- COI transparency: This clarification actually reduces promotional ambiguity by being explicit about boundaries
- 5. Development section (restructured)
- Rationale: Clearly delineates open-source tools from commercial offerings
- Why: Current version is vague about what's proprietary vs. open; proposed version is transparent
- Sources: Project documentation, license information
- COI transparency: Explicit separation reduces confusion and improves neutrality
- 6. Features section (new, with subsections)
- Rationale: Consolidates technical information with proper structure
- Why: Current version scatters feature info; proposed version organizes systematically
- Subsections:
- Diagram Types: Expanded list with version reference
- Syntax: Adds code example (standard for programming tool articles)
- Usage: Documents workflows including CI/CD and AI integration
- Sources: Official documentation, platform documentation
- Comparison: Technical tool articles typically include syntax examples
- 7. Integrations section (restructured and expanded)
- Rationale: Better organization by integration type
- Why: Current bullet list is flat and incomplete; proposed structure is more navigable
- Subsections:
- Main platforms (GitHub, GitLab, Azure DevOps)
- Editors and IDEs (VSCode, JetBrains, Notion, etc.)
- Work management (Confluence, Jira, Microsoft 365)
- AI tools (GitHub Copilot, MCP)
- Sources: Official platform documentation, vendor docs
- Why expanded: Integration ecosystem is significant part of the project's adoption
- 8. Comparison section (new)
- Rationale: Helps readers understand positioning in ecosystem
- Why: Common Wikipedia convention for software articles; addresses "how is this different from X?"
- Covers:
- diagrams.net (draw.io): Visual editor approach
- PlantUML: Alternative text-based tool
- Graphviz: Graph layout focus
- Sources: Third-party tool documentation
- Neutrality: Explicitly states "without implying preference"
- Comparison: React article has similar comparison to Vue/Angular; Git has comparison to other VCS
- 9. Reception section (expanded)
- Rationale: Provides broader context beyond single award
- Why: Developer media coverage is notable and verifiable
- Sources: Developer media, tech publications
- Comparison: Similar software articles document media reception
- ================================================================
- Quantitative comparison
Metric Current Proposed Change Word count ~250 ~1,100 +340% Main sections 1 (lead) 8 +7 sections Subsections 0 6 +6 Code examples 0 1 +1 Citations 18 54 +36 Structure depth Flat 2-3 levels Improved - ================================================================
- Why the expansion is appropriate
- Project has 74,000+ GitHub stars (top 0.1% of GitHub projects)
- Used by major platforms (GitHub, GitLab, Microsoft, Atlassian)
- Published technical book (Packt, 2021)
- $7.5M funding indicates market significance
- Current ~250 words is stub-like compared to similar projects
- Comparable articles:
- PlantUML: ~900 words with similar structure
- Graphviz: ~1,200 words
- D3.js: ~800 words
- ================================================================
- COI mitigation
- As disclosed, I work for Mermaid Chart Inc. To mitigate COI concerns:
- All content is factual and well-sourced
- Clear separation between open-source and commercial reduces ambiguity (improves neutrality)
- Comparison section includes competing tools
- No promotional language or unsupported claims
- No exaggeration of features or adoption
- Focus on encyclopedic information
- All claims verifiable through third-party sources
- ================================================================
- I'm happy to address any specific concerns or questions about individual sections. If editors prefer a different structure or want certain sections removed/modified, I'm open to iterating on this proposal. Thank you for your time reviewing this! Sleepyfuecoco (talk) 20:02, 20 November 2025 (UTC)
@Sleepyfuecoco: There are a lot of +'s; this is basically a rewrite. Yes, it would be good to improve coverage of this product, but what you've written has a very strong marketing scent. Not a reflection on you specifically, but people who are not independent simply have a hard time writing things that are or even sound independent of the subject. If you don't believe there is anything to be salvaged from the exiting article, we could put your proposal in a sandbox somewhere and let independent editors edit it to remove the marketing flavor from it and try to balance it better. ~Kvng (talk) 21:41, 20 November 2025 (UTC)- There's something wrong with your diff. I've just looked at the article and a lot of the +'d material is already in the article. ~Kvng (talk) 21:42, 20 November 2025 (UTC)
- Hi @Kvng – extremely grateful for this quick feedback, means so much!
- Nevertheless, want to try my best to make it work. Totally understand the marketing scent, I think having independent editors would be so helpful (I tried my best to stay neutral but inevitably it's hard to be unbiased). How does that process work and which sandbox would I post this in?
- And to your note about the diff, let me take a look – sorry for going in circles, can you tell this is my first time T.T .. really appreciate your patience! Sleepyfuecoco (talk) 22:18, 20 November 2025 (UTC)
- Sharing the "updated" version since that might just be easier to read: Sleepyfuecoco (talk) 22:45, 20 November 2025 (UTC)
"updated" version |
|---|
|
Something different
[edit]- Let's try something different. I'm going to create a copy of the current article at Mermaid (software)/Sleepyfuecoco. Can you go and edit this with your proposed changes. We can then use the Wiki diff tool to clearly see what you're proposing. ~Kvng (talk) 04:14, 21 November 2025 (UTC)
- @Kvng: I've moved it to User:Sleepyfuecoco/Mermaid (software) since sandbox articles shouldn't be created in mainspace. Children Will Listen (🐄 talk, 🫘 contribs) 04:25, 21 November 2025 (UTC)
- Thank you so much! @Kvng
- I've updated the page with the new copy (the formatting is a bit off), but content-wise it's up to date! Sleepyfuecoco (talk) 01:16, 27 November 2025 (UTC)
- The formatting actually looks pretty good. I've compared the two files and, perhaps I've done something wrong, but they have very little in common. If this is a complete rewrite, the most obvious path is to queue this draft at WP:AFC with a note that it is a rewrite to replace the existing article and explain why the replacement is better. I'm not sure how that will go over with AFC reviewers. An alternative is to go with your
Happy to break this into smaller requests (e.g., “Integrations” only) if that’s easier to review.
offer and I may be able to help. ~Kvng (talk) 15:20, 27 November 2025 (UTC)- Got it, thank you so much @Kvng! I'll go ahead and submit in the AFC with the rationale; simultaneously could I work with you directly to break it up into smaller requests? Sleepyfuecoco (talk) 22:51, 2 December 2025 (UTC)
- No. I think you should choose one path at a time. ~Kvng (talk) 22:28, 10 December 2025 (UTC)
- Hi @Kvng! I submitted to AFC but was declined and instead recommended to break it up into smaller requests. What would be the most appropriate way to submit incremental updates? Sleepyfuecoco (talk) 22:38, 19 December 2025 (UTC)
- I guess we can work through it. Let's skip the lead for now because the lead should summarize the body. We'll get back to the lead once we understand what in the body will be changing.
- So let's start with the new History section you propose to add. I have combined some repeated references. I have tagged a WP:V issue in the second paragraph. I have not worked past this. Once we have worked through the rest of your new proposed History section, we can consider adding it to the article. ~Kvng (talk) 18:02, 21 December 2025 (UTC)
- Hi @Kvng, so sorry I missed your reply! That sounds perfect to me, thank you so much again for taking the time to help me out.
- RE: WP:V issue in the second paragraph
- Is this source appropriate? Sleepyfuecoco (talk) 20:15, 5 January 2026 (UTC)
- Buchta, Brian (3 June 2024). "Mermaid: Helping Documentation Catch Up with Development". Keyhole Software. Retrieved 5 January 2026.
- Yes, though it is not necessarily a WP:RS, it solves the WP:V issue so is good enough for me for this purpose. ~Kvng (talk) 20:44, 5 January 2026 (UTC)
- Thank you so much! Is there anything else I can provide to help move this along? : ) Sleepyfuecoco (talk) 22:52, 5 January 2026 (UTC)
- You help by editing the draft to include this source and remove my {{fv}} tag. ~Kvng (talk) 03:42, 6 January 2026 (UTC)
- Thank you so much! Is there anything else I can provide to help move this along? : ) Sleepyfuecoco (talk) 22:52, 5 January 2026 (UTC)
- Hi @Kvng! I submitted to AFC but was declined and instead recommended to break it up into smaller requests. What would be the most appropriate way to submit incremental updates? Sleepyfuecoco (talk) 22:38, 19 December 2025 (UTC)
- No. I think you should choose one path at a time. ~Kvng (talk) 22:28, 10 December 2025 (UTC)
- Got it, thank you so much @Kvng! I'll go ahead and submit in the AFC with the rationale; simultaneously could I work with you directly to break it up into smaller requests? Sleepyfuecoco (talk) 22:51, 2 December 2025 (UTC)
- The formatting actually looks pretty good. I've compared the two files and, perhaps I've done something wrong, but they have very little in common. If this is a complete rewrite, the most obvious path is to queue this draft at WP:AFC with a note that it is a rewrite to replace the existing article and explain why the replacement is better. I'm not sure how that will go over with AFC reviewers. An alternative is to go with your
- Moving on then. I don't think we need a separate Publication section. Just add a short sentence to the main history section or include a link to the book in a Further reading or External links section at the end of the article.
- Similarly, Open core company doesn't need to be a separate section, just a paragraph in the History section. We don't need the information about investor funding. You may be tempted to argue that many undeveloped articles have information like this. But it is somewhat promotional, not important to most readers, and generally gets removed as the article is improved, and improvement is what we're trying to do here. ~Kvng (talk) 03:42, 6 January 2026 (UTC)
- Noted! Made the following changes:
- - Removed the [failed verification] tag
- - Removed separate Publication / Open Core Company section
- – Swapped out Publication section with a short sentence
- – Removed investor funding content Sleepyfuecoco (talk) 23:38, 6 January 2026 (UTC)
- Thanks. I have added the new history section to the article. I'll be back to look at next steps in a bit or if you are starting to get the gist of the process, you can propose what we should work on next. I'm going to be busy elsewhere for the next few days. ~Kvng (talk) 14:08, 7 January 2026 (UTC)