Documentation restructure and update

[DanielOaks]

Hi all! I'm Daniel, a tech writer at Sendle. 👋 I've used Mermaid a whole bunch and absolutely love it, but it can be pretty difficult to convince and teach others how to use it.

I'd like to work on restructuring and updating Mermaid's documentation, to make it easier to read through and to help it look nicer! Making an issue is the best way to get thoughts together before diving straight into PRs, so I'll explain more below.

If you've got any thoughts about this, please feel free to toss them in this issue or reach out to me on the Mermaid Slack! I've made the #docs channel over there to coordinate if anyone else is interested.

🤔 Why update Mermaid's docs?

Mermaid is an amazing tool! And with new GitHub, Notion, and other integrations, it's being used by more people every day. Including by more non-developers. The current documentation works, but I think a restructure could make things a lot more findable, especially for people new to the project.

Here's some issues I think a restructure could solve:

• Dev-focused content (e.g. API usage) and non-dev content are mixed together, meaning people who are trying to make Mermaid diagrams need to search to find which pages (and parts of pages) are aimed at them.
• Existing integrations are pretty hidden, and showing these off could help people justify learning/using Mermaid more.
• Some important information (like the fact that rendering user-content-driven diagrams can have security implications) ends up getting obscured with the not-super-structured sidebar.

In addition to the restructure, an update like https://github.com/mermaid-js/mermaid/issues/2163 would make the docs look a lot more modern, let people who like Mermaid justify using it in projects, and help bring more writers into ✨ the Mermaid universe ✨

✍️ What to do?

The first thing I'd like to do is restructure the sidebar, including creating, merging, and splitting pages as described below. Once that's cleaned up, I think either customising docsify to look more modern or looking at alternative docs systems like ReType makes sense.

✨ Proposed new sidebar layout

• 📖 Welcome
  • About Mermaid
  • Why use Mermaid?
  • Existing Integrations
  • Security for User-Generated Diagrams
  • Changelog
• ✍️ Using Mermaid
  • Creating your first diagram
  • Using FontAwesome icons
  • Refining diagrams
  • Other Tutorials
  • Advanced use
• 📊 Diagrams
  • Diagram Types and Syntax
  • ... all the diagram types here ...
• 🛠️ Developers
  • Using the API
  • Using the CLI
  • Directives
  • Theming
  • Contributing to Mermaid
  • Adding a new diagram/chart
• 👋 Community
  • Community spaces
  • Suggesting new features
  • Reporting bugs
• 🔐 Security

Welcome

This section is a bit of a grab-bag for important pages, and for people who are evaluating Mermaid.

---

• About Mermaid (e)
  • Contains mostly the same content, minus Diagram Types (that'll live under Diagrams) and Security (that deserves its own page).
• Why use Mermaid? (n)
  • New page that describes the whys in terms of Mermaid vs other diagram/graphing systems. Focusing on why Mermaid is useful is a good thing.
• Existing Integrations (e)
  • Most people who use Mermaid are going to use it through GitHub's inbuilt support, or GitLab's, or through some other existing plugin! So let's put these front and centre, maybe even showing off some logos to make it easier to browse.
• Security for User-Generated Diagrams (e)
  • This is an important point, and I think splitting it out into its own dedicated page here makes sense.
• Changelog (e)
  • I just think having this up here makes sense ¯\_(ツ)_/¯

Using Mermaid

This section is all about actually using Mermaid to make diagrams. If you want to make a diagram, then this first section will be super helpful for you!

---

• Creating your first diagram (n/e)
  • Just a page about getting started with Mermaid. Getting familiar with the syntax, using the live editor to see and modify examples, all that kind of thing.
• Using FontAwesome icons (e)
  • Mermaid's FontAwesome support is super cool, and I love using Mermaid so much because I can embed existing icons into it. I think emphasising this makes sense, and we can expand this page a lot with more tips and tricks
• Refining diagrams (n)
  • This page will go through taking a basic diagram and making it look fancier by changing the layout of it, adding icons, changing node shapes, etc. It's easy to make diagrams with Mermaid, but making ones that don't look out-of-place when using fancy modern doc systems can be difficult, so let's give tips on how to do this specifically.
• Other tutorials (e)
• Advanced use (n)
  • There's a lot of interesting things you can do with Mermaid, including using Directives, Themes, and even more.
• FAQ (e)

Diagrams

This section is just a lil rename of the Diagram Syntax section, with an extra page up the top.

---

• Diagram Types and Syntax (e, e)
  • Basic overview of the types of diagrams you can make with Mermaid, and the basic syntax that Mermaid uses.

Developers

This section is for people developing Mermaid and wanting to integrate Mermaid into their own projects!

---

• Using the API (e)
• Using the CLI (e)
• Directives (e)
• Theming (e)
• Contributing to Mermaid (e)
• Adding new diagram types (e)

Community

This section's about the Mermaid community, and how the community can help Mermaid!

---

• Community spaces (n)
  • We can describe accessing Slack from here, and even more places to find like-minded Mermaid friends!
• Suggesting new features (n)
  • Having a page that describes how to suggest new features makes sense.
• Reporting bugs (n)
  • Same for having a page about reporting bugs.

Security

This'll basically be the current Security page, just dressed up as its own section because it probably deserves it.

---

• Security (e, e)

[knsv]

Hi! Sorry for the slow response. I think your proposal looks interesting. Are you still interested in working with this?

Thanks, Knut

[DanielOaks]

Hi @knsv, sure! No worries at all. I'm definitely still interested in this 👀

[qurm]

Hi - I'd be happy to assist here with reviewing or editing.

I am a long time but casual user of Mermaid, so I dont know it too well, so I'll appreciate having some well structured documents. I agree with Daniels comments and I think the structure has not kept up with the growth of Mermaid. e.g. it can be hard to tell what applies to the whole tool, and what is specific to a single diagram type.

[knsv]

This could be aligned with another documentation issue: #3484

[DanielOaks]

Oh, nice call out! I'll keep an eye on how that issue progresses and look at performing this work in conjunction with / after it resolves.

[weedySeaDragon]

This is great, @DanielOaks . I'm also interested in helping out with the documentation. I wrote my thoughts in a Discussion (I don't think Discussion were enabled when you submitted this.) I'd like to see some milestones defined for the documentation. Your proposal would definitely be a great one!

I'm a software engineer (since the 80s!) and a large part of my focus is to always make sure the information is organized in the best way possible for its users. Documentation -- of all kinds -- most definitely is a part of it

I have been using plantUML, but have be frustrated at its disorganization from the start. (Both with the documentation, how the project is done, and the underlying code.) A friend told me about mermaid and I'm glad. Although it doesn't yet have all of the bells and whistles as plantUML, it's got a sound foundation.

Glad you're going to be able to help!
Perhaps we can continue developing ideas over in the Discussions.

[emersonbottero]

https://github.com/mermaid-js/mermaid/pull/3678. It should shows conflicts but I can't see them.

[weedySeaDragon]

I can't see them iether @emersonbottero . Perhaps one of the maintainers can help out: @sidharthv96 ? @knsv ?

[nirname]

There is also opened issue #3744

[nirname]

Stripe documentation is quite often referred as extremely good, and I fully agree with that. Have a look at their interactive tutorials. Our goal should be to add something as eloquent and self-descriptive.

[nirname]

When I started contributing, I realized that contribution part of the documentation is far from perfect. The most important commands to start development were missing or scattered across multiple documents. I did not received much guidance through the process. So that is what the majority of the developers face (if not everyone) when they want to join the project.

The same can be applied for regular users. They need a clear and easy guide.

Here is the list of ideas, not only about development section. Some of them are already done or in progress, I keep them here too for the record.

I wish the following improvements would be done:

• [x] Sidebar menu not foldable, though it was intended to be #4742
• [x] Development pages are very long and it's left and right sidebars are wrong #4744
• [x] Remove n00b filenames #4767
• [ ] Add Quick Start Quide as a short version of configuring local development environment, we need to make entry as easy as possible #5132
• [ ] Bring CONTRIBUTING.md and README.md as close as possible to documentation. @aloisklink wanted it to be done and that is really important because they tend to diverge with the documentation. While setting up the project I was mislead by that difference #5132
• [ ] Development pages have /community in URL's. It could be cleaner if we would move this to /development/ (not sure, we need to discuss this). Perhaps development and community sections must be split #5132
• [ ] Revise Contributing Code section #5132
• [ ] Revise Contributing Documentation section #5132
• [ ] Revise Questions And Suggestions section #5132
• [ ] Improve Adding new Diagrams (may be this is what @Yokozuna59 was going to add)
• [ ] Add test to make sure all new file names are kebab-case for the documentation
• [ ] For every diagram configuration options section of doc must be generated automatically or checked against schema
• [ ] It would be nice to have syntax diagram for every diagram (I am mastering tautology) (there is a specific EBNF diagram in progress for that, but I postponed it)
• [ ] Sidebar does not keep its state (folded unfolded) while switching between pages. I have not researched yet, maybe it is Vitepress-related cc @emersonbottero

I am not sure that:

• Using the API
• Using the CLI
• Directives
• Theming

have to be under Development section, because it is basically example of usage, although an advanced one. Not sure about Theming though.

Rework About Mermaid:

• [ ] Exclude contribution section, refer to development pages and/or CONTRIBUTING.md
• [ ] Extract security section, leave links to the dedicated page
• [ ] Extract installation section, redirect to quick start guide
• [ ] Extract deployment section as well
• [ ] Remove diagram types in their current state, may be replace them with kinda https://datavizproject.com/ thumbnails

Other:

• [ ] Rework Getting Started, this is actually unclear what should I do to start using Mermaid at the first glance.
• [ ] Move Tutorials to "ecosystem" out of "deployment and configuration" because it represents some third party things
• [ ] "Tutorials" link, that leads to external 3rd party guides at the top menu seems a bit excessive alongside Docs. Docs are enough

The opening sentence at the main page:

It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically

sounds unnatural to me. It is grammatically correct but seems fussy and over complicated (renders ... to create)

• [ ] Add section for maintainers. There are some uncovered company policies about merge practices, publishing npm packages, etc.

[emersonbottero]

Sidebar does not keep its state (folded unfolded) while switching between pages. I have not researched yet, maybe it is Vitepress-related cc we should update to the latest vitepress (we can wait when it is released, now it is rc10)

[Encr1pt0r]

Hi @nirname and @DanielOaks,

Thank you for making such detailed information about updates to the documentation on Mermaid!

Looking at contributing here for the first time and I have forked and cloned the develop branch onto my machine.

I also have some questions, on the "Contributing Documentation" page is it true that you still need to fork from master instead of develop? Also, I looked at the package.json file and could not find the pnpm docs:dev script, is there a new alternative that I should be aware of if I were to make changes?

I am willing to work on anything you see as a good fit as well, I just picked one that looked interesting to me

[emersonbottero]

the repo has several packages.. the docs script are here

[nirname]

Hi @Encr1pt0r, thanks for your interest. Contributing documentation section is still under development. We will update it ASAP. Command docs:dev is inside another package:

npx pnpm run --filter mermaid docs:dev