diff --git a/docs/intro/getting-started.md b/docs/intro/getting-started.md index 95d7b594e0..a6d3bd5cd2 100644 --- a/docs/intro/getting-started.md +++ b/docs/intro/getting-started.md @@ -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 + +
+ +#### • 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 @@ -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. +
+ +#### • 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 +
+ +#### • 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: +
-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 +
+ +#### • 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 + +
+ +#### • 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: + + + +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`. + -### 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 +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, +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 `
`:**
+- This is an example of an embedded Mermaid diagram definition inside a `
`:
 
 ```html
 
   Here is a mermaid diagram:
   
-        graph TD 
-        A[Client] --> B[Load Balancer] 
-        B --> C[Server01] 
+        graph TD
+        A[Client] --> B[Load Balancer]
+        B --> C[Server01]
         B --> D[Server02]
   

 
 ```
 
-**Notes**: Every Mermaid chart/graph/diagram definition, should have separate `
` tags.
+> **Note**
+> Every Mermaid chart/graph/diagram definition should have separate `
` 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 `
` 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 `
` tags and renders them into diagrams.
 
 ```html
 
@@ -134,8 +230,8 @@ b. The importing of mermaid library through the `mermaid.esm.mjs` or `mermaid.es
 
 ```
 
-**Notes**:
-Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doing the opposite lets you control when it starts looking for `
` tags inside the web page with `mermaid.initialize()`. This is useful when you think that not all `
` 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 `
` tags inside the web page with `mermaid.initialize()`. This is useful when you think that not all `
` 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()`
 
@@ -143,9 +239,7 @@ Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doi
 | ----------- | --------------------------------- | ------- | ----------- |
 | 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
 
@@ -175,8 +269,7 @@ Rendering in Mermaid is initialized by `mermaid.initialize()` call. However, doi
 
 ```
 
-**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
 
@@ -204,21 +297,30 @@ In this example mermaid.js is referenced in `src` as a separate JavaScript file,
 
 ```
 
----
+## 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 `