Documentation restructure and update

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)

[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.

[knsv]

This could be aligned with another documentation issue: #3484