Add mermaid for graphs

[Boegie19]

What does it do?

Allow us to make graphs with mermaid inside of the docs

Why is it needed?

So that we for example can better explain relations between different things for example the cycle of going from request to response

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
documentation	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 6, 2023 2:15pm

[pwizla]

Thanks, @Boegie19. As mentioned in the Contribution guide's introduction, this kind of implementation, which could modify the UI and UX of the Strapi Documentation product and should be evaluated as part of our roadmap, should be discussed with the Strapi Documentation team :) Thanks for opening the PR, though, which will allow us to open the discussion on the topic.

We've considered Mermaid multiple times (edit: adding a link so that other readers can know what we're talking about 🙂).
✅ The main pro is that it's text-based, which makes it relatively easy to use and helps keep track of changes in a git-based, version-controlled system.
❌ The main con is that the default rendered result is usually not really pleasant to the eyes (subjective) and does not respect the Strapi branding guidelines (objective). Even though theming is possible, we should allocate some internal resources to vastly improve the output, if possible at all.

The good news is that the specific topic you mention ("for example the cycle of going from request to response") is part of our quarterly objectives. The Documentation team is indeed currently doing some research to improve the Backend customization section. Adding more illustrations to this section is part of the objectives. We'd like to hear community feedback so please feel free to fill in the Google Form.

You probably already noticed it was shared in a Discord message. If you have other ideas and want to discuss these in person, I'd be happy to schedule a call with you :)

[Boegie19]

@pwizla I see where you are coming from.

How I see it having diagrams of for example the request to response cycle would help the understandability of the docs for new users a lot also an other + point for mermaid is that you can link to other stuff in the docs what you can't do with anything else what is not text based and that in my personal option would overrule nice graphs that you can't click on to go to what that part of the graph is showing

an example of it being used is https://missingstrapidocs.com/guide/diagrams/lifecycle.html

I also think that with graphs in this cease it would be better to start with them sooner and them being bad-ish and then over time if we know for sure it is useful for the strapi docs at that point then you can start working on custom theming doing that from the start without knowing how useful it would be could be a big waste of time.

[pwizla]

That's an interesting and useful way of viewing the problem. Thanks for sharing! We'll discuss this internally and see what we can do. As I mentioned, adding illustrations is on our list, and the final design is an important part of our decisions process. We are also considering other tools. I'll let you know once we've gone further in our discussions.

[Boegie19]

Forgot to say but

As mentioned in the Contribution guide's introduction, this kind of implementation, which could modify the UI and UX of the Strapi Documentation product and should be evaluated as part of our roadmap, should be discussed with the Strapi Documentation team :) Thanks for opening the PR, though, which will allow us to open the discussion on the topic.

This is never mentioned specifically in the Contribution guide

[pwizla]

To my knowledge, it is:

We appreciate your interest and efforts to contribute to Strapi! Though all contributions are highly appreciated, we recommend you talk to a maintainer (@pwizla or @meganelacheny) prior to investing a lot of time in a pull request that may not align with the project roadmap.

Again, I'm happy to schedule a call with you if you'd like to brainstorm or discuss the topic :)

[Boegie19]

@pwizla sure I would like that call

also interpreted that line as don't spend 30 min+ on a pr before asking not UI and UX changes need a rfc ;)

[pwizla]

NIce! Let's schedule a call. We'll reach out to you soon on Discord :)

[pwizla]

also interpreted that line as don't spend 30 min+ on a pr before asking not UI and UX changes need a rfc ;)

I've just modified the contributing guide to be more exhaustive :) Thanks for the feedback.

[pwizla]

Hey @Boegie19!
Just wanted to let you know that, in the end, I'll approve this PR :)
We've rediscussed the topic internally and considered all aspects and different tools. Though we still don't like the default result of diagrams generated by Mermaid, it still appears as the best solution to use right now because it's easier to maintain, easier to keep track of versions, does not make the Strapi documentation team or community users depend on designers, and is ready to integrate with Docusaurus.
We'll probably heavily customize the CSS for the end result. That's why I updated the target branch to next, as I don't consider Mermaid "production-ready" yet for us. The next branch is auto-deployed on docs-next.strapi.io. We'll use this "next" website to experiment with many topics in the forthcoming months (REST API, backend customization, and more) before pushing this to production on docs.strapi.io.

Thanks again for contributing and sharing your opinion.

[Boegie19]

@pwizla Before we can accept this one we need to pin the versions
since now mermaid will be on the newest version because of the ^
What breaks everying I did that in my other pr

[pwizla]

(note to self: Need to re-add that to the PR)

[Boegie19]

Would it not be better to set noIndex to an env variable that defaults to false and is set to true only on main?

[pwizla]

Would it not be better to set noIndex to an env variable that defaults to false and is set to true only on main?

Absolutely, it's just that I don't have admin rights to the Vercel projects to set the env vars 😅 So if I do this right now in the code without any way to pass the env var to the build process, the default value will be applied to both environments. It should actually be set to true on the next branch (we don't want to index docs-next) and to false on the main branch. cc @derrickmehaffy we discussed it a few weeks ago ^^

[derrickmehaffy]

Would it not be better to set noIndex to an env variable that defaults to false and is set to true only on main?

Absolutely, it's just that I don't have admin rights to the Vercel projects to set the env vars sweat_smile So if I do this right now in the code without any way to pass the env var to the build process, the default value will be applied to both environments. It should actually be set to true on the next branch (we don't want to index docs-next) and to false on the main branch. cc @derrickmehaffy we discussed it a few weeks ago ^^

I will set the var for the production right now but have a chat with me @pwizla so we can actually test this before you merge.

[derrickmehaffy]

Var is DOCU_NO_INDEX

[pwizla]

Thanks, Derrick! I've just added this to my to do list for next week, will schedule a chat with you. Thank you 😊

[pwizla]

I will close this one as Mermaid got added to our Docusaurus setup with the first published backend customization section improvements. Thanks again for the suggestion and discussion, Boegie19!