Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: update Getting Started page #5112

Merged
merged 2 commits into from
Dec 19, 2023
Merged

Docs: update Getting Started page #5112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
276b5c7
update getting started page
huynhicode Dec 4, 2023
2469419
additional updates
huynhicode Dec 19, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
228 changes: 165 additions & 63 deletions docs/intro/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,44 @@
>
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/intro/getting-started.md](../../packages/mermaid/src/docs/intro/getting-started.md).

# A Mermaid User-Guide for Beginners
# Mermaid User Guide

Mermaid is composed of three parts: Deployment, Syntax and Configuration.
## Mermaid is composed of three parts

This section talks about the different ways to deploy Mermaid. Learning the [Syntax](syntax-reference.md) would be of great help to the beginner.
1. Deployment
2. Syntax
3. Configuration

> Generally the live editor is enough for most general uses of mermaid, and is a good place to start learning.
This section talks about the different ways to **deploy** Mermaid.

**Absolute beginners are advised to view the Video [Tutorials](../config/Tutorials.md) on the Live Editor, to gain a better understanding of mermaid.**
If you are a beginner:

## Four ways of using mermaid:
- Check out the [Diagram Syntax](syntax-reference.md) page
- Check out the [Tutorials](../config/Tutorials.md) page

1. Using the Mermaid Live Editor at [mermaid.live](https://mermaid.live).
2. Using [mermaid plugins](../ecosystem/integrations-community.md) with programs you are familiar with.
3. Calling the Mermaid JavaScript API.
4. Deploying Mermaid as a dependency.
## Ways to use Mermaid

**Note: It is our recommendation that you review all approaches, and choose the one that is best for your project.**
1. [Using the Mermaid Live Editor](getting-started.md#_1-using-the-mermaid-live-editor)
2. [Using the Mermaid Chart Editor](getting-started.md#_2-using-the-mermaid-chart-editor)
3. [Using Mermaid Plugins and Integrations](getting-started.md#_3-using-mermaid-plugins)
4. [Calling the Mermaid JavaScript API](getting-started.md#_4-calling-the-mermaid-javascript-api)
5. [Adding Mermaid as a dependency](getting-started.md#_5-adding-mermaid-as-a-dependency)

> More in depth information can be found at [Usage](../config/usage.md).
To learn more, visit the [Usage](../config/usage.md) page.

## 1. Using the Live Editor
## 1. Using the Mermaid Live Editor

Available at [mermaid.live](https://mermaid.live)
Available at the [Mermaid Live Editor](https://mermaid.live) website.

### Features

<br />

#### • Diagram Code

In the `Code` panel, write or edit Mermaid code, and instantly `Preview` the rendered result in the diagram panel.

Here is an example of Mermaid code and its rendered result:

```mermaid-example
graph TD
Expand All @@ -51,79 +65,161 @@ graph TD
F --> B
```

In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it.
<br />

#### • Configurations

The `Configuration` Section is for changing the appearance and behavior of mermaid diagrams. An easy introduction to mermaid configuration is found in the [Advanced usage](../config/advanced.md) section. A complete configuration reference cataloging the default values can be found on the [mermaidAPI](../config/setup/README.md) page.
Configuration options are available in the `Configuration` panel. The options are applied to the diagram in the `Preview` panel.

For learn more, visit the [Configuration Reference](../config/setup/README.md) page

![Code,Config and Preview](./img/Code-Preview-Config.png)

### Editing History
<br />

#### • Editing History

Your code will be autosaved and appear in the `Timeline` tab of the `History` section. Edits are saved every minute and only the last 30 edits are viewable.

Your code will be autosaved every minute into the Timeline tab of History which shows the most recent 30 items.
Alternatively, you can manually save code by clicking on the `Save` icon from the `History` section.

You can manually save code by clicking the Save icon in the History section. It can also be accessed in the Saved tab. This is stored in the browser storage only.
> **Note**
> History is stored in the browser storage only.

### Saving a Diagram:
<br />

You may choose any of the methods below, to save it
#### • Saving a diagram

**We recommend that you save your diagram code on top of any method you choose, in order to make edits and modifications further down the line.**
There are multiple ways of saving your diagram from the `Actions` section:

- export PNG
- export SVG
- export as Markdown

![Flowchart](./img/Live-Editor-Choices.png)

### Editing your diagrams
<br />

#### • Editing your diagrams

To edit your diagram, you can copy paste existing Mermaid diagram code into the `Code` section of the `Live Editor`.

Or:

- create a new diagram from scratch
- use a Sample Diagram from the `Sample Diagrams` section

<br />

#### • Loading from Gists

The Gist you create should have a `code.mmd` file and optionally a `config.json`, similar to this [example](https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a).

> **Note**
> To learn about Gists, visit the GitHub documentation page on [Creating gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists).

Once you have created a Gist, copy paste the Gist URL into the respective field in the `Actions` section and click on the `Load Gist` button.

Here is an example of a Gist being loaded into the Editor:

<https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a>

And, here is the diagram view from the above example:

Editing is as easy as pasting your **Diagram code**, into the `code` section of the `Live Editor`.
<https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a>

### Loading from Gists
## 2. Using the Mermaid Chart Editor

The Gist you create should have a code.mmd file and optionally a config.json. [Example](https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a)
Available at the [Mermaid Chart](https://www.mermaidchart.com/) website.

To load a gist into the Editor, you can use <https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a>
Mermaid Chart is a web-based diagram editor that allows you to create and edit diagrams in your browser. It is built by the team behind Mermaid.

and to View, <https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a>
Features include:

## 2. Using Mermaid Plugins:
- AI diagramming
- Collaboration & multi-user editing
- Storage
- and more

You can generate mermaid diagrams from within popular applications using plug-ins. It can be done in the same way, you would use the Live Editor. Here's a list of [Mermaid Plugins](../ecosystem/integrations-community.md).
To learn more, visit the [Mermaid Chart page](/ecosystem/mermaid-chart.html) in the Ecosystem section of the documentation.

**This is covered in greater detail in the [Usage section](../config/usage.md)**
Or go to the [Mermaid Chart website](https://www.mermaidchart.com/app/sign-up) to sign up for a Free account.

## 3. Calling the JavaScript API
## 3. Using Mermaid Plugins

This method can be used with any common web server like Apache, IIS, nginx, node express.
### Mermaid Plugins

You will also need a text editing tool like Notepad++ to generate a .html file. It is then deployed by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer).
You can generate Mermaid diagrams from within popular applications using plug-ins.

For a list of Mermaid Plugins and Integrations, visit the [Integrations page](../ecosystem/integrations-community.md).

### Mermaid Chart Plugins

Mermaid Chart plugins are available for:

- [ChatGPT](https://docs.mermaidchart.com/plugins/chatgpt)
- [JetBrains IDE](https://docs.mermaidchart.com/plugins/jetbrains-ide)
- [Microsoft PowerPoint](https://docs.mermaidchart.com/plugins/microsoft-powerpoint)
- [Microsoft Word](https://docs.mermaidchart.com/plugins/microsoft-word)
- [Visual Studio Code](https://docs.mermaidchart.com/plugins/visual-studio-code)

To learn more, visit the [Mermaid Chart Plugins](https://www.mermaidchart.com/plugins) page.

### Native Mermaid Support

For apps that support markdown (e.g. [GitHub](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) and [GitLab](https://handbook.gitlab.com/handbook/tools-and-tips/mermaid/)), you can add Mermaid diagrams by making a `mermaid` code block.

````markdown
The following code-block will be rendered as a Mermaid diagram:

```mermaid
flowchart LR
A --> B
```
````

## 4. Calling the Mermaid JavaScript API

This method can be used with any common web server like `Apache`, `IIS`, `Nginx`, and `Node Express`.

You will also need a text editing tool like `Notepad++` to generate an `html` file. It is then deployed by a web browser, i.e. `Firefox`, `Chrome`, `Safari`.

> **Note**
> Internet Explorer is not supported.

The API works by pulling rendering instructions from the source `mermaid.js` in order to render diagrams on the page.

### Requirements for the Mermaid API.
### Requirements for the Mermaid API

When writing the `html` file, we give two instructions inside the `html code` to the `web browser`:

When writing the .html file, we give two instructions inside the html code to the web browser:
a. The Mermaid code for the diagram we want to create.

a. The mermaid code for the diagram we want to create.
b. The importing of the Mermaid library through the `mermaid.esm.mjs` or `mermaid.esm.min.mjs`, and the `mermaid.initialize()` call, which dictates the appearance of diagrams and also starts the rendering process.

b. The importing of mermaid library through the `mermaid.esm.mjs` or `mermaid.esm.min.mjs` and the `mermaid.initialize()` call, which dictates the appearance of diagrams and also starts the rendering process.
#### Examples

**a. The embedded mermaid diagram definition inside a `<pre class="mermaid">`:**
- This is an example of an embedded Mermaid diagram definition inside a `<pre class="mermaid">`:

```html
<body>
Here is a mermaid diagram:
<pre class="mermaid">
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
</pre>
</body>
```

**Notes**: Every Mermaid chart/graph/diagram definition, should have separate `<pre>` tags.
> **Note**
> Every Mermaid chart/graph/diagram definition should have separate `<pre>` tags.

**b. The import of mermaid and the `mermaid.initialize()` call.**
- This is an example of a Mermaid import and the `mermaid.initialize()` call.

`mermaid.initialize()` call takes all the definitions contained in all the `<pre class="mermaid">` tags that it finds in the html body and renders them into diagrams. Example:
> **Note**
> A `mermaid.initialize()` call takes all the definitions contained within `<pre class="mermaid">` tags and renders them into diagrams.

```html
<body>
Expand All @@ -134,18 +230,16 @@ b. The importing of mermaid library through the `mermaid.esm.mjs` or `mermaid.es
</body>
```

**Notes**:
Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doing the opposite lets you control when it starts looking for `<pre>` tags inside the web page with `mermaid.initialize()`. This is useful when you think that not all `<pre>` tags may have loaded on the execution of `mermaid.esm.min.mjs` file.
> **Note**
> Rendering in Mermaid is initialized by the `mermaid.initialize()` call. However, doing the opposite lets you control when it starts looking for `<pre>` tags inside the web page with `mermaid.initialize()`. This is useful when you think that not all `<pre>` tags may have loaded on the execution of `mermaid.esm.min.mjs` file.

`startOnLoad` is one of the parameters that can be defined by `mermaid.initialize()`

| Parameter | Description | Type | Values |
| ----------- | --------------------------------- | ------- | ----------- |
| startOnLoad | Toggle for Rendering upon loading | Boolean | true, false |

### Working Examples

**Here is a full working example of the mermaidAPI being called through the CDN:**
In this example, the `mermaidAPI` is being called through the `CDN`:

```html
<html>
Expand Down Expand Up @@ -175,8 +269,7 @@ Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doi
</html>
```

**Another Option:**
In this example mermaid.js is referenced in `src` as a separate JavaScript file, in an example Path.
In this example, `mermaid.js` is referenced in `src` as a separate JavaScript file:

```html
<html lang="en">
Expand Down Expand Up @@ -204,21 +297,30 @@ In this example mermaid.js is referenced in `src` as a separate JavaScript file,
</html>
```

---
## 5. Adding Mermaid as a dependency

## 4. Adding Mermaid as a dependency.
Below are the steps for adding Mermaid as a dependency:

1. install node v16, which would have npm
1. Install `node v16`

2. download yarn using npm by entering the command below:
npm install -g yarn
> **Note**
> To learn more about downloading and installing `Node.js` and `npm`, visit the [npm Docs website](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).

3. After yarn installs, enter the following command:
yarn add mermaid
1. Install `yarn` using `npm` with this command:

4. To add Mermaid as a Dev Dependency
yarn add --dev mermaid
`npm install -g yarn`

**Comments from Knut Sveidqvist, creator of mermaid:**
2. After yarn installs, enter this command:

- In early versions of mermaid, the `<script>` tag was invoked in the `<head>` part of the web page. Nowadays we can place it in the `<body>` as seen above. Older parts of the documentation frequently reflect the previous way which still works.
`yarn add mermaid`

3. To add Mermaid as a dev dependency, enter this command:

`yarn add --dev mermaid`

## Closing note

> **Note**
> Comments from Knut Sveidqvist, creator of Mermaid:
>
> - In early versions of Mermaid, the `<script>` tag was invoked in the `<head>` part of the web page. Nowadays, we can place it in the `<body>` as seen above. Older parts of the documentation frequently reflect the previous way, which still works.