Docs update and restructure

[nirname]

📑 Summary

When I started contributing, I realized that contribution part of the documentation is far from perfect. The most important commands to start development are missing or scattered across multiple documents.

Revise documentation #2910 #3416 #3744

📏 What has been done and why

• Left / sidebar menu was not foldable because of the wrong option. Now it is and expanded by default
• Split development page into several pages, previous one was far too big to read it briefly
• Because of nested sections in the contributing section of left (sidebar) menu buttons Prev Page, Next Page were not working
• Some commands to start the development was missing added
• Removed links to obsolete n00b-overview page and the page itself
• Added documentation for development in Docker and cross links between host and docker installation guides
• Fixed top menu (added link to contribution sections)
• Added component to switch between installation modes
• Added section "Why use Mermaid" to the intro (this probably will be separate page)
• CONTRIBUTING.md now a symlink to documentation part
• Inside introduction page Rely on css classes rather than document on structure

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added unit/e2e tests (if appropriate)
• 📓 have added documentation (if appropriate)
• 🔖 targeted develop branch

[codecov]

Codecov Report

Merging #4596 (711b40b) into master (eb397fd) will increase coverage by 5.03%.
Report is 125 commits behind head on master.
The diff coverage is 70.58%.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4596      +/-   ##
==========================================
+ Coverage   72.15%   77.18%   +5.03%     
==========================================
  Files         144      145       +1     
  Lines       14583    14659      +76     
  Branches      563      586      +23     
==========================================
+ Hits        10522    11315     +793     
+ Misses       3931     3233     -698     
+ Partials      130      111      -19     

Flag	Coverage Δ
e2e	83.90% <83.92%> (+6.62%)	⬆️
unit	46.10% <47.91%> (+0.77%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files Changed	Coverage Δ
packages/mermaid/src/dagre-wrapper/shapes/util.js	96.22% <ø> (-1.89%)	⬇️
packages/mermaid/src/diagrams/c4/c4Diagram.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/c4/svgDraw.js	87.65% <ø> (ø)
...ages/mermaid/src/diagrams/class/classDiagram-v2.ts	60.00% <ø> (ø)
packages/mermaid/src/diagrams/er/erRenderer.js	93.47% <ø> (ø)
...s/mermaid/src/diagrams/flowchart/flowDiagram-v2.ts	75.00% <ø> (ø)
...ackages/mermaid/src/diagrams/gantt/ganttDiagram.ts	100.00% <ø> (ø)
...ckages/mermaid/src/diagrams/git/gitGraphDiagram.ts	100.00% <ø> (ø)
...mermaid/src/diagrams/mindmap/mindmap-definition.ts	100.00% <ø> (ø)
packages/mermaid/src/diagrams/pie/pieDiagram.ts	100.00% <ø> (ø)
... and 24 more

... and 17 files with indirect coverage changes

[sidharthv96]

Can we keep the docs pure markdown?
This is a small feature, but it's a slippery slope, and we might have to do another BIG change to get out of vitepress later.

[nirname]

It is much more readable and transparent with those switch buttons. Two separate sections or pages that kinda duplicate each other looks very bulky, not to mention their maintenance. Is there any plans to get rid of Vitepress in the nearest future? For some cases we obviously need something more than plain markdown.

[aloisklink]

My feeling is that this file needs to be pure Markdown too, ideally in Markdown that is applicable to both GitHub-Flavored Markdown and Vitepress (so no Vitepress specific features, and no GFM specific features).

GitHub has a nice UI that tells first-time contributors when they make a PR to read the CONTRIBUTING.md file, so ideally we'd put everything into that file, and just copy it to Vitepress for the website.

As a workaround, you could instead do something like:

## Setup and Launch

_If you'd prefer to develop in a Docker container, please see [Setup and Launch using Docker](#setup-and-launch-using-docker)_

[nirname]

Removed

[sidharthv96]

Use ```tip, not the ::: one.

[nirname]

I faced some issues with it. Only ::: was working properly. I will try it again. Perhaps the problem was with its content. I needed a code block inside

[nirname]

Done

[sidharthv96]

Can we remove the n00b from the file names?

We should setup the redirects in redirects.ts file.

[nirname]

I decided not to redo everything in one batch, that will be done in upcoming requests. Applying changes and simultaneous renaming of a file can cause diff become meaningless.

[sidharthv96]

Why collapse everything?

[nirname]

This option did not worked at all, I simply renamed the option, the value left intact. If we want our sidebar to be expanded by default, I'll change its value too

[nirname]

Now everything is expanded by default and menu is collapsible. If we don't want to make it collapsible, we need to remove the option entirely

[aloisklink]

Thanks for taking a look at improving the documentation! I agree with most of @sidharthv96's points, but I have some other thoughts too:

My gut feeling is that our README.md file should be exactly the same (or as similar as possible) to the packages/mermaid/src/docs/intro/index.md file.

I also feel like the CONTRIBUTING.md should be as similar as possible to the packages/mermaid/src/docs/community/x file.

Does it make sense to combine the:

• packages/mermaid/src/docs/community/code.md,
• packages/mermaid/src/docs/community/development.md, and
• packages/mermaid/src/docs/community/documentation.md

files into a single big packages/mermaid/src/docs/community/CONTRIBUTING.md file, that we can then symlink or copy to CONTRIBUTING.md?

---

Btw, there are a bunch of TODO messages in the documentation. Are those intended to be there? If yay, we might want to mark this PR as a draft until they're all fixed.

[aloisklink]

My feeling is that this file needs to be pure Markdown too, ideally in Markdown that is applicable to both GitHub-Flavored Markdown and Vitepress (so no Vitepress specific features, and no GFM specific features).

GitHub has a nice UI that tells first-time contributors when they make a PR to read the CONTRIBUTING.md file, so ideally we'd put everything into that file, and just copy it to Vitepress for the website.

As a workaround, you could instead do something like:

## Setup and Launch

_If you'd prefer to develop in a Docker container, please see [Setup and Launch using Docker](#setup-and-launch-using-docker)_

[nirname]

Does it make sense to combine the:

packages/mermaid/src/docs/community/code.md,
packages/mermaid/src/docs/community/development.md, and
packages/mermaid/src/docs/community/documentation.md
files into a single big packages/mermaid/src/docs/community/CONTRIBUTING.md file, that we can then symlink or copy to CONTRIBUTING.md?

Yes, it does. I think it will be put in order in a separate request.

Btw, there are a bunch of TODO messages in the documentation. Are those intended to be there? If yay, we might want to mark this PR as a draft until they're all fixed.

No, this is not a draft. Almost all of those TODO's are current part of documentation.

They will be addressed in a separate batch of changes

[aloisklink]

Looks better!

I've figured out why the ![]()... shields in packages/mermaid/src/docs/intro/index.md wasn't working, see fix in #4596 (comment)

---

Does it make sense to combine the:

• packages/mermaid/src/docs/community/code.md,
• packages/mermaid/src/docs/community/development.md, and
• packages/mermaid/src/docs/community/documentation.md

files into a single big packages/mermaid/src/docs/community/CONTRIBUTING.md file

Yes, it does. I think it will be put in order in a separate request.

If you can, sticking it in this PR would make the git diff a lot simpler, and so:

1. This would make the PR easier to review.
2. It would make merge conflicts less likely to happen.

But I know using git rebase to clean up commits can be pretty difficult, and this is just documentation, not code, so it's not too big of a deal if you don't want to do it.

I think we should at least definitely combine the packages/mermaid/src/docs/community/development.md and packages/mermaid/src/docs/community/docker-development.md files, since those two are very similar (and the docker-development.md file has some custom Vitepress YAML front-matter that will be difficult to keep in sync with the sidebar).

[aloisklink]

Would it be easier to just have the Docker instructions in the same file as the non-docker instructions?

E.g. something like:

## Get the Source Code

## Technical Requirements

> The following documentation describes how to work with Mermaid in your host
> environment. There's also a
> [Docker installation guide](#docker-development) if you prefer to
> work in a Docker environment.

## Setup and Launch

### Switch to project

### Install packages

### Launch

## Verify Everything is Working

## Docker Development

> The following documentation describes how to work with Mermaid in a Docker
> environment. Go back to
> [Technical Requirements](#technical-requirements) if you want to
> to work in your host environment, without Docker.

### Docker Technical Requirements

### Make `./run` executable

### Install packages in Docker

### Launch in Docker

### Verify Everything is Working in Docker

[nirname]

I don't know. In terms of supporting this - many be. But I think combining would rather distract readers. There are many similar parts inside, some phrases are repeated too. I'd rather stick to separate page instead of a long and bewildering one. I don't actually know. I am not a technical writer.

[aloisklink]

Hmmmmm, I still think having everything in one file is nicer, but I'm not a technical writer either 😆.

Having everything in a single file would be much cleaner from a writing perspective, and it will make it easier to work with the documentation.

But having them in two separate files might be better for readers.

@sidharthv96, any thoughts?

[nirname]

I think I am the only one who develops it in Docker...

[aloisklink]

I think I am the only one who develops it in Docker...

I'm generally using Docker too (well, podman, but from a user's perspective, Podman is pretty similar to Docker).

Although I'm currently running all the commands manually, which works pretty well, except for opening the Cypress GUI. It looks like the ./run script handles Cypress pretty well, so the next time I need to debug a Cypress E2E test, I'll probably read your docs on how to get it working in Docker 😄.

[weedySeaDragon]

Thanks for thinking of me, @nirname . Probably not able to get to it any time soon, though.

[nirname]

@aloisklink You give me controversial instructions.
Current contribution page is in terrible state

• Left and right sidebars are identical this meaningless
  

• Having direct links with anchors in the left menu breaks previous and next pages buttons, e.g. when clicking https://mermaid.js.org/community/development.html#contributing-documentation previous page is ok, but next must be "Adding Diagrams" or "Questions or Suggestions"
  

• Right menu displays only 2nd level headings (and skips the others), left menu is not one that builds on the fly, and a user cannot really see the steps that are needed for installation or for contributing to documentation

• Consequently, the combined CONTRIBUTIONS.md page which I even had not even planned to alter at the first approach looks messy

You said that it CONTRIBUTIONS.md (and that is a combinations of files)

is still pretty messy, which isn't great
with which I agree, and at the same you think
the easiest and cleanest thing to do is delete the code.md/documentation.md/development.md/docker-development.md file and rewrite them into one big single file

Which one is true?

We could rewrite development.md to have links to code.md/documentation.md/etc. Then we can symlink the CONTRIBUTING.md file to development.md.
May be but is development.md even with links is enough for reader to start with?

The the major part of this PR is simplifying and splitting the pages. If we decide to combine pages we simply will end up were we started, this is exactly opposite of what I am trying to achieve here. So if you think this is wrong, lets simply reject it.

---

• I was targeting this to development
• Then I was suggested to rebase my

  PR to master, so we can release it faster.
  from @sidharthv96 in Slack

• Then I received a comment from you to target development branch and rebased it onto develop again
  And now documentation development for me is broken and stuck (in this branch and in development branch as well), because
  I receive this error

Uncaught (in promise) ReferenceError: defineOptions is not defined
    at setup (VPImage.vue:10:1)
    at callWithErrorHandling (runtime-core.esm-bundler.js:173:22)
    at setupStatefulComponent (runtime-core.esm-bundler.js:7265:29)

upon which I dont know what to do

So the whole PR became messy

[sidharthv96]

This has to go into develop, otherwise we'd get a lot of merge conflicts.

@aloisklink the plan was to merge the docs change to master, and then merge master to develop as usual. I'm not sure how that would develop conflicts? If any conflicts do arise, we can resolve them when merging master to develop.

@nirname should we squash and merge this as a single commit?

Consequently, the combined CONTRIBUTIONS.md page which I even had not even planned to alter at the first approach looks messy

My understanding was that the CONTRIBUTIONS.md is a very minimal set of instructions to get someone who is already familiar with development started on mermaid. We can have links to the detailed instructions from there.

I suggest we stick to the original plan and not make any changes to CONTRIBUTIONS.md in this PR.

But having them in two separate files might be better for readers.
@sidharthv96, any thoughts?

@nirname highlighted some points on why keeping them separate is better. Let's keep them separate.
It won't confuse the readers too.

[sidharthv96]

Converting to draft so avoid acciendtally merging to master.

[nirname]

@sidharthv96 I think I'll redo it, the whole PR is unusable. Guidelines says to target develop, so let's stick to that. I'll split this PR into several parts so that it would be easier to review. I still cannot launch docs:dev without getting error, nevertheless

[huynhicode]

@sidharthv96 I think I'll redo it, the whole PR is unusable. Guidelines says to target develop, so let's stick to that. I'll split this PR into several parts so that it would be easier to review. I still cannot launch docs:dev without getting error, nevertheless

@nirname This works for me:

cd into /packages/mermaid/src/docs
run pnpm dev
open up localhost:3333

I know you are doing a new PR and wanted to throw in my two cents:

• It would be nice to split different set-up environments into separate files - good from a readers' standpoint and for
  making updates.
• The side panel (left side) should be treated more so like navigation and the table of contents (right side where it says, "On this page") is a guide for user's to quickly access content within a document. I'm in favor of simplifying the side panel so that it only contains page links and not section links.
• I am not sure anyone makes updates to the documentation by way of the "Edit this page on GitHub" functionality. I am in favor of removing this option.
• I like that sections of the side panel can be collapsed as there are a lot of pages and users have to scroll a bit to see all the sections/pages. Should be expanded by default though.
• I'm favor of shorter pages - easier to find content.

Based on the Mermaid JS slack workspace, it looks like there is a sprinkling of users looking to contribute (to docs and diagrams), so concise and clear instructions would be really great.

I usually share something like this when someone mentions they are interested in contributing:

Check out this list of good first issues. And read our docs on contributing.

Some instructions on getting started:

Get started:

• fork the repo
• clone the repo
• cd into the forked repo
• install Volta
• run volta install node
• run volta install pnpm
• run npx pnpm install

To contribute to the documentation:

• cd into /packages/mermaid/src/docs
• run pnpm dev
• open up localhost:3333

To contribute to the core code:

• at the root folder, run pnpm dev
• open up localhost:9000
• make modifications to /packages/mermaid/src/
  (e.g. to update the flowchart found at localhost:9000/flowchart.html, go to /packages/mermaid/src/diagrams/flowchart)

To add E2E Tests:

• run pnpm dev
• run pnpm exec cypress open

To submit a Pull Request:

• run pnpm test
• run pnpm lint:fix (if there is a formatting issue)

[nirname]

@huynhicode Thanks for advice. Does

pnpm run --filter mermaid docs:dev

works in your case in development branch?

[Yokozuna59]

@nirname It won't work because the argument appears after --filter should be the name in package.json.

This should work:

pnpm run --filter docs docs:dev

sorry I thought it was a command in docs not mermaid :)

[huynhicode]

pnpm run --filter mermaid docs:dev

@nirname Yes, this works for me.

I am on the develop branch and ran the command from here: mermaid/packages/mermaid/src/docs.

[nirname]

@huynhicode no, I am asking specifically about whether this command:

pnpm run --filter mermaid docs:dev

works when you are in the root of mermaid project and at develop branch?

If this one does not work, the only point of going directly to packages/mermaid/src/docs and runing commands from here is to use it as a temporary workaround. Otherwise we are turning a blind eye on a development stopper and there is no sense in supporting docs:dev in the root package.json

[huynhicode]

pnpm run --filter mermaid docs:dev

This command also works for me at the root in the develop branch.

I think open source contribution should be a fun experience and not being able to set up or run the project locally is a huge deterrent. I really would like to foster a robust community, so I am in favor of whatever we need to do to make contributions to the docs or to Mermaid syntax as seamless a process as possible.

[Yokozuna59]

@nirname I was planning to update the Create New Diagram JISON section in #4727, but I saw you have modified the file here, and it would have conflicts. But since you closed this PR, should I modify it there or wait for the new PR?

[nirname]

@Yokozuna59 I am going to split instruction into different files, so it's better to wait for my PR's.

[aloisklink]

Consequently, the combined CONTRIBUTIONS.md page which I even had not even planned to alter at the first approach looks messy

Sorry, that's my fault, I should have been clearer. My main worry was that the current CONTRIBUTING.md would diverge from the docs/community/development.md, which is important since GitHub's UI heavily pushes all contributors to read the CONTRIBUTING.md file.

I felt like making CONTRIBUTING.md just point to your updated docs/community/development.md file was the easiest way to keep everything in sync. But @sidharthv96's recommendation, and just having the CONTRIBUTING.md points to the detailed instructions, works just as well if we want to have instructions in separate files.

---

Then I was suggested to rebase my "PR to master, so we can release it faster." from @sidharthv96 in Slack

Ah, sorry, I saw the "targeted develop branch" in your PR description, and thought you made a mistake targeting master.

(I swear I saw that your PR also had some commits from @Yokozuna59 too, so I assumed those were commits from the develop branch that weren't yet on master, but maybe that was just GitHub's UI glitching out!)

The whole merging to master, and merging master back to develop is a weird practice that I've only seen the Mermaid project do, and it tends to cause merge conflicts, which are often not fixed correctly (e.g. semantic merge conflicts). It also makes commands like git bisect harder to run.

As an example, if @Yokozuna59 had edited the same files on the develop branch that you did on the main branch, either Knut or @sidharthv96 would manually have to fix merge conflicts when merging main into develop (or vice versa) and this has caused things to break in the past. Sometimes git also auto-merges in a way that causes bugs, so git doesn't throw an error, but stuff still breaks (also has happened multiple times in the Mermaid project, but GitHub's PR Merge Queue should prevent them, as long as all merges are done by GitHub in a PR).

Of course if @sidharthv96 says it's okay, Sid should know what's in both develop and master and so it should be okay to merge manually :)

---

👍 on switching this to smaller PRs! I know making smaller PRs is a lot more work, but it does making reviewing a lot easier; a big PR like this might take 1-2 hours to review, so it can be a struggle for me to find time to review a big PR (it often needs to wait until the weekend), so smaller PRs are super appreciated by me 😄!

And even when I'm using other third-party libraries, smaller PRs make it a lot easier to figure out what has changed between releases, so I'm sure Mermaid users will appreciate them too!

---

• I am not sure anyone makes updates to the documentation by way of the "Edit this page on GitHub" functionality. I am in favor of removing this option.

I agree with everything else @huynhicode says in #4596 (comment), but I tend to use the "Edit this page on GitHub" link all the time (both in the Mermaid project and other projects), in order to find out which documentation file I need to edit, so please don't remove it! But I wouldn't mind changing it to "View the source for this file on GitHub", because I almost never use GitHub's UI to edit anything.

[nirname]

@aloisklink No worries, the whole PR was a sloppy one, because it addressed to many different problems at once.
I am planning to update everything you have suggested at subsequent stages.

We will:

• Make shorter version of development pages (aka Quick Start Guide)

So yes, there will be one page version for the reader to refer to.

Then we will bring:

• CONTRIBUTING.md
• README.md

as close as possible to documentation pages

Also:

• Remove n00b from file names
• Add some new sections like 'Why use Mermaid'

Plus some other changes.

I think I will add my ideas to #2910

I will target develop branch regardless of other other release policies and processes, because it is much cleaner for a developer and a reviewer too (although it takes more time). So there won't be confusion caused by unclear commits history.