Skip to content

Commit

Permalink
update getting started page
Browse files Browse the repository at this point in the history
  • Loading branch information
@huynhicode
huynhicode committed Dec 4, 2023
1 parent 9be9601 commit 276b5c7
Show file tree
Hide file tree
Showing 2 changed files with 324 additions and 124 deletions.
218 changes: 156 additions & 62 deletions docs/intro/getting-started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,61 @@
>
> ## 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 Chart Editor](getting-started.html#_1-using-the-mermaid-chart-editor)
2. [Using the Mermaid Live Editor](getting-started.html#_1-using-the-mermaid-chart-editor)
3. [Using Mermaid Plugins and Integrations](getting-started.html#_3-using-mermaid-plugins)
4. [Calling the Mermaid JavaScript API](getting-started.html#_4-calling-the-mermaid-javascript-api)
5. [Adding Mermaid as a dependency](getting-started.html#_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 Chart Editor

Available at [mermaid.live](https://mermaid.live)
Available at the [Mermaid Chart](https://www.mermaidchart.com/) website.

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.

Features include:

- AI diagramming
- Collaboration & multi-user editing
- Storage
- and more

To learn more, visit the [Mermaid Chart page](/ecosystem/mermaid-chart.html) in the Ecosystem section of the documentation.

Or go to the [Mermaid Chart website](https://www.mermaidchart.com/app/sign-up) to sign up for a Free account.

## 2. Using the Mermaid Live Editor

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 +82,132 @@ 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 every minute into the Timeline tab of History which shows the most recent 30 items.
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.

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.
Alternatively, you can manually save code by clicking on the `Save` icon from the `History` section.

### Saving a Diagram:
> **Note**
> History is stored in the browser storage only.
You may choose any of the methods below, to save it
<br />

**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.**
#### • Saving a diagram

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:

Editing is as easy as pasting your **Diagram code**, into the `code` section of the `Live Editor`.
- create a new diagram from scratch
- use a Sample Diagram from the `Sample Diagrams` section

### Loading from Gists
<br />

The Gist you create should have a code.mmd file and optionally a config.json. [Example](https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a)
#### • Loading from Gists

To load a gist into the Editor, you can use <https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a>
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).

and to View, <https://mermaid.live/view?gist=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).
## 2. Using Mermaid Plugins:
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.

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).
Here is an example of a Gist being loaded into the Editor:

**This is covered in greater detail in the [Usage section](../config/usage.md)**
<https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a>

## 3. Calling the JavaScript API
And, here is the diagram view from the above example:

This method can be used with any common web server like Apache, IIS, nginx, node express.
<https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a>

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).
## 3. Using Mermaid Plugins

### Mermaid Plugins

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 & Word](https://docs.mermaidchart.com/plugins/microsoft-office)
- [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.

## 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.
<br />

**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 +218,18 @@ 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
<br />

**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 +259,9 @@ 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.
<br />

In this example, `mermaid.js` is referenced in `src` as a separate JavaScript file:

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

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

Below are the steps for adding Mermaid as a dependency:

## 4. Adding Mermaid as a dependency.
1. Install `node v16`

1. install node v16, which would have npm
> **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).
2. download yarn using npm by entering the command below:
npm install -g yarn
1. Install `yarn` using `npm` with this command:

3. After yarn installs, enter the following command:
yarn add mermaid
`npm install -g yarn`

4. To add Mermaid as a Dev Dependency
yarn add --dev mermaid
2. After yarn installs, enter this command:

**Comments from Knut Sveidqvist, creator of mermaid:**
`yarn add 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.
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.
Loading

0 comments on commit 276b5c7

Please sign in to comment.