Improving the documentation and using Swimm for up-to-date docs

[Omerr]

Hello Mermaid team 👋🏻
I am Omer from Swimm.

I have to say that I really love using Mermaid, and have been doing it a lot lately, and I had an idea.
How about we use Swimm to generate Mermaid's documentation (on https://mermaid.js.org/) so it is kept up to date automatically?

I can take care of converting the current documentation everything to Swimm, and then using Swimm we will generate everything in vitepress format.
I can also create a few additional docs with things I found useful while going through Mermaid's code.
Of course, using Swimm in Open Source projects is free.

We can also take this opportunity for a content overhaul for the docs.

Please let me know what you think.

[sidharthv96]

Hi Omer, can you clarify some points?

1. Which diagrams are you planning to update?
2. How would the workflow change?
3. Will swimm work locally in the CI machine (like prettier, eslint, etc), or does it require connection to your servers?
4. Can you open a PR with an example change? Maybe one page changed?

[Omerr]

Hi @sidharthv96 , thank you for replying!

1. Which diagrams are you planning to update?
   I think we should make a few updates:
   (a) Whenever possible, take diagrams included in the tests. In this case, if something ever changes in the code and thus in the tests, it will also change in the documents. For example, using diagrams from cypress/integration/rendering/sequencediagram.spec.js.
   (b) There are other references to code parts - such as the API, or paths (e,g,, in https://mermaid.js.org/config/directives.html).

2. How would the workflow change?
   On every PR, Swimm's app will run to verify the docs are up to date. If they are not, a check will fail and then the developer will be able to update the documentation. On most cases this is done automatically.
   I think the simplest way would be to export from Swimm to markdown, and then continue with the flow as is.

3. Will swimm work locally in the CI machine (like prettier, eslint, etc), or does it require connection to your servers?
   The GitHub app works with a hook and connecting to the servers.
   It is also possible to run Swimm's check locally in the CI via Swimm's CLI.

4. Can you open a PR with an example change? Maybe one page changed?
   Definitely. Let's agree on the desired flow and I will be happy to demonstrate it p🙏🏻

[sidharthv96]

1. The changes should be to packages/mermaid/src/docs and docs.mts (if necessary).
2. We should preserve the current build steps (so swimm should not emit vitepress format).
3. GitHub App vs CLI doesn't matter at this stage, so feel free to use whichever is easiest for you.