Refined contribution guide again

packages/mermaid/src/docs/.vitepress/config.ts

@@ -75,12 +75,12 @@ function nav() {
     {
       text: 'Tutorials',
       link: '/ecosystem/tutorials',
-      activeMatch: '/ecosystem/',
+      activeMatch: '/ecosystem/tutorials',
     },
     {
       text: 'Integrations',
       link: '/ecosystem/integrations-community',
-      activeMatch: '/ecosystem/',
+      activeMatch: '/ecosystem/integrations-community',
     },
     {
       text: 'Contributing',

packages/mermaid/src/docs/community/contributing.md

@@ -12,9 +12,9 @@ Initial setup consists of 3 main steps:
 flowchart LR
   source --> requirements --> setup
 
-  source[Get the source code]
+  source[Get the Source Code]
-  requirements[Install the requirements]
+  requirements[Install the Requirements]
-  setup[Install packages]
+  setup[Install Packages]
 ```
 
 ### Get the Source Code
@@ -41,7 +41,7 @@ cd mermaid
 
 We support **development within Docker** environment along with **host setup**. You may choose it up to your preferences.
 
-#### Host
+**Host**
 
 These are the tools we use for working with the code and documentation:
 
@@ -50,7 +50,7 @@ These are the tools we use for working with the code and documentation:
 - [pnpm](https://pnpm.io/) package manager. `volta install pnpm`
 - [npx](https://docs.npmjs.com/cli/v8/commands/npx) the packaged executor in npm. This is needed [to install pnpm.](#install-packages)
 
-#### Docker
+**Docker**
 
 [Install Docker](https://docs.docker.com/engine/install/). And that is pretty much all you need.
 
@@ -63,9 +63,9 @@ echo $DISPLAY
 
 If the `$DISPLAY` variable is not empty, then an X11 server is running. Otherwise you may need to install one.
 
-### Install packages
+### Install Packages
 
-#### Host
+**Host**
 
 Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't support it yet.
 
@@ -73,7 +73,7 @@ Run `npx pnpm install`. You will need `npx` for this because `volta` doesn't sup
 npx pnpm install # npx is required for first install
 ```
 
-#### Docker
+**Docker**
 
 For development using Docker there is a self-documented `run` bash script, which provides convenient aliases for `docker compose` commands.
 
@@ -113,30 +113,49 @@ pnpm test
 
 The `test` script and others are in the top-level `package.json` file.
 
-All tests should run successfully without any errors or failures. (You might see _lint_ or _formatting_ warnings; those are ok during this step.)
+All tests should run successfully without any errors or failures.
+
+```note
+You might see _lint_ or _formatting_ warnings. Those are ok during this step.
+```
 
 ## Workflow
 
+Contributing process is very simple and strightforward:
+
+```mermaid-nocode
+  flowchart LR
+
+  branch --> changes --> submit
+  branch[Checkout a New Branch]
+  changes[Make Changes]
+  submit[Submit a PR]
+```
+
 Mermaid uses a [Git Flow](https://guides.github.com/introduction/flow/)–inspired approach to branching.
 
 Development is done in the `develop` branch.
 
-Once development is done we create a `release/vX.X.X` branch from `develop` for testing.
-
-Once the release happens we add a tag to the `release` branch and merge it with `master`. The live product and on-line documentation are what is in the `master` branch.
-
-The basic steps to start contributing code and documentation are:
-
 ```mermaid-nocode
-  flowchart TB
+---
-
+config:
-  branch --> update --> submit --> review --> branch
+  gitGraph:
-  branch[Checkout a new branch]
+    mainBranchName: develop
-  update[Make changes]
+---
-  submit[Submit a PR]
+gitGraph LR:
-  review[Review and merge]
+  commit
+  commit
+  branch "docs/2910_update-guidelines" order: 1
+  commit
+  commit
+  commit
+  checkout develop
+  merge "docs/2910_update-guidelines"
+  commit
 ```
 
+To prepare a new version we create a `release/vX.X.X` branch from `develop` for testing. Once the release happens we add a tag to the `release` branch and merge it with `master`. The live product and on-line documentation are what is in the `master` branch.
+
 ## Checkout a New Branch
 
 ```tip
@@ -388,13 +407,13 @@ pnpm docs:dev
 
 **Docker**
 
-```
+```bash
 ./run docs:dev
 ```
 
 Open [http://localhost:3333/](http://localhost:3333/) in your browser.
 
-### Format
+### Formatting
 
 The documentation is written in Markdown. To get acquainted with its syntax [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).
 
@@ -404,6 +423,8 @@ You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a n
 Do not use vitepress specific markdown syntax `::: warning` as it will not be processed correctly.
 ```
 
+Here are a few examples:
+
 ````markdown
 ```note
 This is a note
@@ -422,11 +443,25 @@ This is a danger alert
 ```
 ````
 
+```note
+This is a note
+```
+
+```tip
+This is a tip
+```
+
+```warning
+This is a warning
+```
+
+```danger
+This is a danger alert
+```
+
 ### Navigation
 
-If you want to propose changes to how the documentation is _organized_, such as adding a new section or re-arranging or renaming a section, you must update the **sidebar navigation.**
+If you want to propose changes to how the documentation is _organized_, such as adding a new section or re-arranging or renaming a section, you must update the **sidebar navigation**, which is defined in [the vitepress config](../.vitepress/config.ts). The same goes to **topbar**.
-
-The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts).
 
 ## Submit your pull request
 
@@ -440,7 +475,7 @@ git push -u origin docs/2910_update-contributing-guidelines
 
 We make all changes via Pull Requests (PRs). Open a new one.
 
-Right now we are not following any strict rules about naming PRs. Give it a representative title and short description. There is also a [pull_request_template](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it.
+Right now we are not following any strict rules about naming PRs. Give it a representative title and short description. There is also a [pull request template](https://github.com/mermaid-js/mermaid/blob/develop/.github/pull_request_template.md) which will help you with it.
 
 In case in its description contains a [magic comment](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) your PR will be automatically attached to the issue:
 
@@ -448,8 +483,6 @@ In case in its description contains a [magic comment](https://docs.github.com/en
 Resolves #<your issue ID here>
 ```
 
-You can edit it if needed.
-
 ## Congratulations
 
 You have successfully submitted your improvements! What is next?

packages/mermaid/src/docs/community/documentation.md

@@ -48,7 +48,7 @@ pnpm docs:dev
 
 **Docker**
 
-```
+```bash
 ./run docs:dev
 ```