marcel/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-09-12 03:49:43 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
nirname
2023-12-21 00:44:22 +00:00
parent dfa0ad5b7a
commit d54d13ef28
4 changed files with 126 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

90
docs/community/contributing.md
View File

@@ -18,9 +18,9 @@ Initial setup consists of 3 main steps:
flowchart LR
source --> requirements --> setup
source[Get the source code]
requirements[Install the requirements]
setup[Install packages]
source[Get the Source Code]
requirements[Install the Requirements]
setup[Install Packages]
```
### Get the Source Code
@@ -47,7 +47,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:
@@ -56,7 +56,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.
@@ -69,9 +69,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.
@@ -79,7 +79,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.
@@ -118,30 +118,48 @@ 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
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
flowchart TB
branch --> update --> submit --> review --> branch
branch[Checkout a new branch]
update[Make changes]
submit[Submit a PR]
review[Review and merge]
---
config:
gitGraph:
mainBranchName: develop
---
gitGraph LR:
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**
@@ -395,11 +413,13 @@ pnpm docs:dev
**Docker**
./run docs:dev
```bash
./run docs:dev
```
Open <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).
@@ -408,6 +428,8 @@ You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a n
> **‼️ Danger**
> 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
@@ -426,11 +448,21 @@ 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.**
The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts).
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**.
## Submit your pull request
@@ -443,7 +475,7 @@ The sidebar navigation is defined in [the vitepress configuration file config.ts
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:
@@ -451,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?

4
docs/community/documentation.md
View File

@@ -59,7 +59,9 @@ pnpm docs:dev
**Docker**
./run docs:dev
```bash
./run docs:dev
```
Open <http://localhost:3333/> in your browser.

90
docs/contributing/contributing.md
View File

@@ -18,9 +18,9 @@ Initial setup consists of 3 main steps:
flowchart LR
source --> requirements --> setup
source[Get the source code]
requirements[Install the requirements]
setup[Install packages]
source[Get the Source Code]
requirements[Install the Requirements]
setup[Install Packages]
```
### Get the Source Code
@@ -47,7 +47,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:
@@ -56,7 +56,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.
@@ -69,9 +69,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.
@@ -79,7 +79,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.
@@ -118,30 +118,48 @@ 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
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
flowchart TB
branch --> update --> submit --> review --> branch
branch[Checkout a new branch]
update[Make changes]
submit[Submit a PR]
review[Review and merge]
---
config:
gitGraph:
mainBranchName: develop
---
gitGraph LR:
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**
@@ -395,11 +413,13 @@ pnpm docs:dev
**Docker**
./run docs:dev
```bash
./run docs:dev
```
Open <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).
@@ -408,6 +428,8 @@ You can use `note`, `tip`, `warning` and `danger` in triple backticks to add a n
> **‼️ Danger**
> 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
@@ -426,11 +448,21 @@ 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.**
The sidebar navigation is defined in [the vitepress configuration file config.ts](../.vitepress/config.ts).
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**.
## Submit your pull request
@@ -443,7 +475,7 @@ The sidebar navigation is defined in [the vitepress configuration file config.ts
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:
@@ -451,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?

4
docs/contributing/documentation.md
View File

@@ -59,7 +59,9 @@ pnpm docs:dev
**Docker**
./run docs:dev
```bash
./run docs:dev
```
Open <http://localhost:3333/> in your browser.