Merge pull request #4 from mermaid-js/develop

Merge from main

.github/pr-labeler.yml

@@ -0,0 +1,3 @@
+'Type: Bug / Error': 'bug/*'
+'Type: Enhancement': 'feature/*'
+'Type: Other': 'other/*'

.github/release-drafter.yml

@@ -0,0 +1,21 @@
+name-template: '$NEXT_PATCH_VERSION'
+tag-template: '$NEXT_PATCH_VERSION'
+categories:
+  - title: '🚀 Features'
+    labels:
+      - 'Type: Enhancement'
+  - title: '🐛 Bug Fixes'
+    labels:
+      - 'Type: Bug / Error'
+  - title: '🧰 Maintenance'
+    label: 'Type: Other'
+change-template: '- $TITLE (#$NUMBER) @$AUTHOR'
+branches:
+  - develop
+no-changes-template: 'This release contains minor changes and bugfixes.'
+template: |
+  # Release Notes
+
+  $CHANGES
+
+  🎉 **Thanks to all contributors helping with this release!** 🎉

.github/workflows/pr-labeler.yml

@@ -0,0 +1,13 @@
+name: Apply labels to PR
+on:
+  pull_request:
+    types: [opened]
+
+jobs:
+  pr-labeler:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Label PR
+        uses: TimonVS/pr-labeler-action@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-draft.yml

@@ -0,0 +1,15 @@
+name: Draft Release
+
+on:
+  push:
+    branches:
+      - develop
+
+jobs:
+  draft-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Draft Release
+        uses: toolmantim/release-drafter@v5.2.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/release-preview-publish.yml

@@ -8,15 +8,12 @@ on:
 jobs:
   publish:
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        node-version: [10.x]
     steps:
     - uses: actions/checkout@v1
-    - name: Setup Node.js ${{ matrix.node-version }}
+    - name: Setup Node.js
       uses: actions/setup-node@v1
       with:
-        node-version: ${{ matrix.node-version }}
+        node-version: 10.x
     - name: Install Yarn
       run: npm i yarn --global
 
@@ -24,7 +21,7 @@ jobs:
       run: npm i json --global
 
     - name: Install Packages
-      run: yarn install
+      run: yarn install --frozen-lockfile
 
     - name: Publish
       run: |

.github/workflows/release-publish.yml

@@ -0,0 +1,46 @@
+name: Publish release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - uses: fregante/setup-git-token@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v1
+      with:
+        node-version: 10.x
+    - name: Install Yarn
+      run: npm i yarn --global
+
+    - name: Install Json
+      run: npm i json --global
+
+    - name: Install Packages
+      run: yarn install --frozen-lockfile
+
+    - name: Prepare release
+      run: |
+        VERSION=${GITHUB_REF:10}
+        echo "Preparing release $VERSION"
+        git checkout -t origin/release/$VERSION
+        npm version --no-git-tag-version --allow-same-version $VERSION
+        git add package.json
+        git commit -m "Bump version $VERSION"
+        git checkout -t origin/master
+        git merge -m "Release $VERSION" --no-ff release/$VERSION
+        git push --no-verify
+
+    - name: Publish
+      run: |
+        npm set //registry.npmjs.org/:_authToken $NPM_TOKEN
+        npm publish
+      env:
+        NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.vscode/settings.json

@@ -1,8 +0,0 @@
-{
-  "typescript.format.enable": false,
-  "typescript.reportStyleChecksAsWarnings": false,
-  "typescript.validate.enable": false,
-  "javascript.validate.enable": false,
-  "editor.formatOnSave": false,
-  "editor.snippetSuggestions": "top"
-}

README.md

@@ -27,7 +27,7 @@ C -->|One| D[Result 1]
 C -->|Two| E[Result 2]
     </pre></td>
     <td align="center">
-        <img src="./img/gray-flow.png" />
+        <img src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-flow.png" />
     </td>
 </tr>
 <!-- </Flowchart> -->
@@ -49,7 +49,7 @@ John->>Bob: How about you?
 Bob-->>John: Jolly good!
     </pre></td>
     <td align="center">
-        <img src="./img/gray-sequence.png" />
+        <img src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-sequence.png" />
     </td>
 </tr>
 <!-- </Sequence> -->
@@ -70,7 +70,7 @@ Parallel 3   :         des5, after des3, 1d
 Parallel 4   :         des6, after des4, 1d
     </pre></td>
     <td align="center">
-        <img src="./img/gray-gantt.png" />
+        <img src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-gantt.png" />
     </td>
 </tr>
 <!-- </Gantt> -->
@@ -99,7 +99,7 @@ class Class10 {
 }
 </pre></td>
     <td align="center">
-        <img src="./img/gray-class.png" />
+        <img src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-class.png" />
     </td>
 </tr>
 <!-- </Class> -->
@@ -119,7 +119,7 @@ Moving --> Crash
 Crash --> [*]
 </pre></td>
     <td align="center">
-        <img src="./img/gray-state.png" />
+        <img src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-state.png" />
     </td>
 </tr>
 <!-- </State> -->
@@ -136,7 +136,7 @@ pie
 "Rats" : 15 
 </pre></td>
     <td align="center">
-        <img src="./img/gray-pie.png" />
+        <img src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-pie.png" />
     </td>
 </tr>
 <!-- </Pie> -->

babel.config.js

@@ -3,9 +3,7 @@ module.exports = {
     [
       '@babel/preset-env',
       {
-        targets: {
-          node: 'current'
-        }
+        targets: "defaults, ie >= 11, current node"
       }
     ]
   ]

cypress/integration/rendering/classDiagram.spec.js

@@ -2,7 +2,7 @@
 import { imgSnapshotTest } from '../../helpers/util';
 
 describe('Class diagram', () => {
-  it('should render a simple class diagram', () => {
+  it('1: should render a simple class diagram', () => {
     imgSnapshotTest(
       `
     classDiagram
@@ -33,7 +33,8 @@ describe('Class diagram', () => {
     );
     cy.get('svg');
   });
-  it('should render a simple class diagrams with cardinality', () => {
+
+  it('2: should render a simple class diagrams with cardinality', () => {
     imgSnapshotTest(
       `
     classDiagram
@@ -132,4 +133,34 @@ describe('Class diagram', () => {
     );
     cy.get('svg');
   });
+
+  it('4: should render a simple class diagram with comments', () => {
+    imgSnapshotTest(
+      `
+    classDiagram
+      %% this is a comment
+      Class01 <|-- AveryLongClass : Cool
+      &lt;&lt;interface&gt;&gt; Class01
+      Class03 *-- Class04
+      Class05 o-- Class06
+      Class07 .. Class08
+      Class09 --> C2 : Where am i?
+      Class09 --* C3
+      Class09 --|> Class07
+      Class07 : equals()
+      Class07 : Object[] elementData
+      Class01 : size()
+      Class01 : int chimp
+      Class01 : int gorilla
+      Class08 <--> C2: Cool label
+      class Class10 {
+        &lt;&lt;service&gt;&gt;
+        int id
+        test()
+      }
+      `,
+      {}
+    );
+    cy.get('svg');
+  });
 });

cypress/integration/rendering/flowchart.spec.js

@@ -14,6 +14,7 @@ describe('Flowcart', () => {
       { flowchart: { htmlLabels: false } }
     );
   });
+
   it('2: should render a simple flowchart with htmlLabels', () => {
     imgSnapshotTest(
       `graph TD
@@ -26,6 +27,7 @@ describe('Flowcart', () => {
       { flowchart: { htmlLabels: true } }
     );
   });
+
   it('3: should render a simple flowchart with line breaks', () => {
     imgSnapshotTest(
       `
@@ -99,6 +101,7 @@ describe('Flowcart', () => {
       {}
     );
   });
+
   it('6: should render a flowchart full of icons', () => {
     imgSnapshotTest(
       `
@@ -178,6 +181,7 @@ describe('Flowcart', () => {
       {}
     );
   });
+
   it('8: should render subgraphs', () => {
     imgSnapshotTest(
       `
@@ -190,7 +194,7 @@ describe('Flowcart', () => {
     );
   });
 
-  it('9: should render subgraphs with a title startign with a digit', () => {
+  it('9: should render subgraphs with a title starting with a digit', () => {
     imgSnapshotTest(
       `
     graph TB
@@ -237,7 +241,7 @@ describe('Flowcart', () => {
     );
   });
 
-  it('11: should render a flowchart with ling sames and class definitoins', () => {
+  it('11: should render a flowchart with long names and class definitions', () => {
     imgSnapshotTest(
       `graph LR
       sid-B3655226-6C29-4D00-B685-3D5C734DC7E1["
@@ -356,6 +360,7 @@ describe('Flowcart', () => {
       }
     );
   });
+
   it('13: should render hexagons', () => {
     imgSnapshotTest(
       `
@@ -377,4 +382,18 @@ describe('Flowcart', () => {
       }
     );
   });
+
+  it('14: should render a simple flowchart with comments', () => {
+    imgSnapshotTest(
+      `graph TD
+      A[Christmas] -->|Get money| B(Go shopping)
+      B --> C{Let me think}
+      %% this is a comment
+      C -->|One| D[Laptop]
+      C -->|Two| E[iPhone]
+      C -->|Three| F[fa:fa-car Car]
+      `,
+      { flowchart: { htmlLabels: false } }
+    );
+  });
 });

cypress/platform/current.html

@@ -0,0 +1,31 @@
+<html>
+  <head>
+    <link
+      href="https://fonts.googleapis.com/css?family=Montserrat&display=swap"
+      rel="stylesheet"
+    />
+
+  </head>
+  <body>
+    <h1>info below</h1>
+    <div class="mermaid">graph TB
+      a --> b
+      a --> c
+      a --> d
+    </div>
+    <script src="./mermaid.js"></script>
+    <script>
+      mermaid.initialize({
+        theme: 'forest',
+        // arrowMarkerAbsolute: true,
+        // themeCSS: '.node rect { fill: red; }',
+        logLevel: 3,
+        flowchart: { curve: 'linear' },
+        gantt: { axisFormat: '%m/%d/%Y' },
+        sequence: { actorMargin: 50 },
+        // sequenceDiagram: { actorMargin: 300 } // deprecated
+      });
+    </script>
+    </script>
+  </body>
+</html>

docs/README.md

@@ -14,10 +14,12 @@ type, state diagrams.
 
 ## Special note regarding version 8.2
 
-In version 8.2 a security improvement was introduced. A securityLevel configuration was introduced wich sets the level of trust to be used on the parsed diagrams.
+In version 8.2 a security improvement was introduced. A securityLevel configuration was introduced which sets the level of trust to be used on the parsed diagrams.
 
 * **true**: (default) tags in text are encoded, click functionality is disabled
-* false: tags in text are allowed, click functionality is enabledClosed issues:
+* false: tags in text are allowed, click functionality is enabled
+
+Closed issues:
 
 ⚠️ **Note** : This changes the default behaviour of mermaid so that after upgrade to 8.2, if the securityLevel is not configured, tags in flowcharts are encoded as tags and clicking is prohibited.
 
@@ -39,7 +41,7 @@ Ever wanted to simplify documentation and avoid heavy tools like Visio when expl
 
 This is why mermaid was born, a simple markdown-like script language for generating charts from text via javascript.
 
-**Mermaid was nomiated and won the JS Open Source Awards (2019) in the catory The most existing use of technology!!! Thanks to all involved, people committing pull requests, people answering questions and special thanks to Tyler Long who is helping me maintain the project.**
+**Mermaid was nominated and won the JS Open Source Awards (2019) in the category "The most exciting use of technology"!!! Thanks to all involved, people committing pull requests, people answering questions and special thanks to Tyler Long who is helping me maintain the project.**
 
 ### Flowchart
 
@@ -168,15 +170,15 @@ https://mermaidjs.github.io
 
 # Request for assistance
 
-Things are piling up and I have hard time keeping up. To remedy this
+Things are piling up and I have a hard time keeping up. To remedy this
 it would be great if we could form a core team of developers to cooperate
-with the future development mermaid.
+with the future development of mermaid.
 
 As part of this team you would get write access to the repository and would
 represent the project when answering questions and issues.
 
 Together we could continue the work with things like:
-* adding more types of diagrams like mindmaps, ert diagrams etc
+* adding more types of diagrams like mindmaps, ert diagrams, etc.
 * improving existing diagrams
 
 Don't hesitate to contact me if you want to get involved.

docs/_sidebar.md

@@ -14,8 +14,15 @@
   - [State Diagram](stateDiagram.md)
   - [Gantt](gantt.md)
   - [Pie Chart](pie.md)
+
 - Guide
 
   - [Development](development.md)
   - [mermaidAPI](mermaidAPI.md)
   - [Changelog](CHANGELOG.md)
+
+- I'm a n00b
+  - [overview](n00b-overview.md)
+  - [Getting started - easier](n00b-gettingStarted.md)
+  - [Diagram syntax intro](n00b-syntaxReference.md)
+  - [Advanced usage](n00b-advanced.md)

docs/classDiagram.md

@@ -322,7 +322,20 @@ class Color{
 }
 ```
 
+## Comments
 
+Comments can be entered within a class diagram, which will be ignored by the parser.  Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any class diagram syntax
+
+```
+classDiagram
+%% This whole line is a comment classDiagram class Shape <<interface>>
+class Shape{
+    <<interface>>
+    noOfVertices
+    draw()
+}
+
+```
 
 ## Styling
 

docs/flowchart.md

@@ -424,6 +424,16 @@ Beginners tip, a full example using interactive links in a html context:
 </body>
 ```
 
+### Comments
+
+Comments can be entered within a flow diagram, which will be ignored by the parser.  Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any flow syntax
+
+```
+graph LR
+%% this is a comment A -- text --> B{node}
+   A -- text --> B -- text2 --> C
+```
+
 ## Styling and classes
 
 ### Styling links

docs/gantt.md

@@ -173,6 +173,23 @@ More info in: http://momentjs.com/docs/#/parsing/string-format/
 
 More info in: https://github.com/mbostock/d3/wiki/Time-Formatting
 
+## Comments
+
+Comments can be entered within a gantt chart, which will be ignored by the parser.  Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax
+
+```
+gantt
+    title A Gantt Diagram
+    %% this is a comment
+    dateFormat  YYYY-MM-DD
+    section Section
+    A task           :a1, 2014-01-01, 30d
+    Another task     :after a1  , 20d
+    section Another
+    Task in sec      :2014-01-12  , 12d
+    another task      : 24d
+
+```
 
 ## Styling
 

docs/index.html

@@ -7,8 +7,20 @@
   <meta name="description" content="Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.">
   <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
   <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
-  <script src="//cdn.jsdelivr.net/npm/mermaid@8.4.1/dist/mermaid.min.js"></script>
-  <!-- <script src="//localhost:9000/mermaid.js"></script> -->
+  <script src="//cdn.jsdelivr.net/npm/mermaid@8.4.3/dist/mermaid.min.js"></script>
+  <script>
+    (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
+    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
+    m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
+    })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
+
+    ga('create', 'UA-153180559-1', 'auto');
+    if(location) {
+       ga('send', 'pageview', location.hash);
+     }
+
+    </script>
+
   <style>
   .markdown-section {
     max-width: 1200px;
@@ -43,8 +55,18 @@
     var num = 0;
     mermaid.initialize({ logLevel:0, startOnLoad: false, themeCSS:'.label { font-family: Source Sans Pro,Helvetica Neue,Arial,sans-serif; }' });
 
+  </script>
+  <script>
+   window.onhashchange = function(a) {
+     //code
+     if(location) {
+       ga('send', 'pageview', location.hash);
+     }
+  }
   </script>
   <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
   <script src="//unpkg.com/docsify/lib/plugins/search.min.js"></script>
+  <scrpt src="//unpkg.com/docsify/lib/plugins/ga.min.js"></scrpt>
 </body>
 </html>
+<!--  -->

docs/mermaidAPI.md

@@ -275,7 +275,7 @@ mermaidAPI.initialize({
 
 <pre>
 
-<script>
+&lt;script>
   var config = {
     theme:'default',
     logLevel:'fatal',
@@ -317,8 +317,7 @@ mermaidAPI.initialize({
     }
   };
   mermaid.initialize(config);
-</script>
-
+&lt;/script>
 </pre>
 
 [1]: https://github.com/knsv/mermaid/blob/master/docs/mermaidAPI.md#render

docs/n00b-advanced.md

@@ -0,0 +1,21 @@
+# Advanced n00b mermaid (Coming soon..)
+
+## splitting mermaid code from html
+A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so:
+
+```
+stuff stuff
+  </div>
+  </body>
+</html>
+```
+The actual mermaid file could for example look like this:
+
+```
+mermaid content...
+```
+---
+
+## mermaid configuration options
+
+...

docs/n00b-gettingStarted.md

@@ -0,0 +1,154 @@
+# A more basic getting started
+
+Writing mermaid code is simple.
+
+But how is the code turned into a diagram in a web page? To do this we need a mermaid renderer.
+
+Thankfully the mermaid renderer is very accessible, in essence it is a javascript.
+
+The requirement is on the part of the web browser. Modern web browsers, such as Firefox, Chrome and Safari, can render mermaid. But Internet Explorer cannot. The web browser also needs access to the online mermaid renderer which it downloads from https://cdn.jsdelivr.net/npm/mermaid
+
+For an easy introduction, here follows three practical examples using:
+1. an online mermaid editor
+2. a mermaid plugin
+3. a generic web server of your choosing
+
+Following either of these examples, you can get started with converting your own mermaid code into web diagrams.
+
+## the mermaid live editor
+
+The quickest way to get started with mermaid is to visit [The mermaid live editor](https://mermaidjs.github.io/mermaid-live-editor).
+
+In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result.
+
+This is a great way to get started.
+
+It is also the easiest way to develop diagrams, the code of which can be pasted straight into documentation.
+
+![Flowchart](./img/n00b-liveEditor.png)
+
+The `Mermaid configuration` is for controlling mermaid behaviour. An easy introduction to mermaid configuration is found in the [Advanced usage](n00b-advanced.md) section. A complete configuration reference cataloguing default values is found on the [mermaidAPI](mermaidAPI.md) page.
+
+
+## mermaid using plugins
+
+Thanks to the growing popularity of mermaid, many plugins already exist which incorporate a mermaid renderer.
+
+One example is the [Atlassian Confluence mermaid plugin](https://marketplace.atlassian.com/apps/1214124/mermaid-plugin-for-confluence?hosting=server&tab=overview)
+
+When the mermaid plugin is installed on a Confluence server, one can insert a mermaid object into any Confluence page.
+
+---
+
+- In a Confluence page, Add Other macros.
+
+![Flowchart](./img/n00b-Confluence1.png)
+
+---
+
+- Search for mermaid.
+
+![Flowchart](./img/n00b-Confluence2.png)
+
+---
+
+- The mermaid object appears. Paste your mermaid code into it.
+
+![Flowchart](./img/n00b-Confluence3.png)
+
+---
+
+- Save the page and the diagram appears.
+
+![Flowchart](./img/n00b-Confluence4.png)
+
+---
+
+## mermaid using any web server (or just a browser)
+
+This example can be used with any common web server. Apache, IIS, nginx, node express [...], you pick your favourite.
+
+We do not need to install anything on the server, apart from a normal file of html to be reached by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer). So if you want to really simplify things when testing this out, don't use a web server at all but just create the file locally and drag it into your browser window. It is the browser which does all the work of rendering mermaid!
+
+Through the html file, we give the web browser three instructions inside the html code it retrieves:
+1. a reference for fetching the online mermaid renderer, the renderer is just a javascript.
+2. the mermaid code we want to diagram.
+3. the `mermaid.initialize()` command to start the rendering process
+
+All this is done in the html `<body>` section of the web page.
+
+This is what needs to go into the html file:
+
+
+
+1. The reference to the mermaid renderer is done in a `<script src>` tag like so:
+
+```
+<body>
+  <script src="https://cdn.jsdelivr.net/npm/mermaid@8.4.0/dist/mermaid.min.js"></script>
+</body>
+```
+
+2. The embedded mermaid code is similarly placed in a `<div>` tag:
+
+```
+<body>
+  Here is a mermaid diagram:
+  <div class="mermaid">
+    graph TD
+    A[Client] --> B[Load Balancer]
+    B --> C[Server01]
+    B --> D[Server02]
+  </div>
+</body>
+```
+
+3. When initializing mermaid using `mermaid.initialize()`, mermaid takes all the `<div class="mermaid">` tags it can find in the html body and starts to render them one by one. This is done like so:
+
+```
+<body>
+  <script>mermaid.initialize({startOnLoad:true});</script>
+</body>
+```
+
+*Finally*
+4. Putting the three steps together is as simple as:
+```
+<html>
+  <body>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid@8.4.0/dist/mermaid.min.js"></script>
+    <script>mermaid.initialize({startOnLoad:true});</script>
+
+    Here is one mermaid diagram:
+    <div class="mermaid">
+      graph TD
+      A[Client] --> B[Load Balancer]
+      B --> C[Server1]
+      B --> D[Server2]
+    </div>
+
+    And here is another:
+    <div class="mermaid">
+      graph TD
+      A[Client] -->|tcp_123| B(Load Balancer)
+      B -->|tcp_456| C[Server1]
+      B -->|tcp_456| D[Server2]
+    </div>
+  </body>
+</html>
+```
+Save this to a html file and fetch it with a browser from the web server (or just drag it into your web browser window) and voila!
+
+---
+
+**Three additional comments from Knut Sveidqvist, creator of mermaid:**
+- In early versions of mermaid, the `<script src>` tag was invoked in the `<head>` part of the web page. Nowdays we can place it directly in `<body>` as seen above. However, older parts of the documentation frequently reflects the previous way which still works.
+  
+- We initialize the mermaid rendering with `mermaid.initialize()` directly in the html code. In principle this could be done through placing `mermaid.initialize()` inside of `mermaid.min.js`. We would then eliminate the need for this explicit line in the html. However, there are use cases where we do want to separate the two steps. Sometimes we want full control over when we start looking for `<div>`tags inside the web page with `mermaid.initialize()`, for example when we think that all `<div>` tags may not have been loaded by the time `mermaid.min.js` runs.
+
+- In the example above, `mermaid.min.js` is called using an absolute path. Even worse, the example includes the mermaid version number which of course will change as time goes by. However, the example makes it easy to understand what is going on - even though it is perhaps doomed in a way we do not want in a production environment. When going from testing mermaid out to getting serious with it, I would suggest one of the following approaches for calling `mermaid.min.js`:
+  
+  1. If you do not enter a specific version, you automatically get the latest one.
+  2. If you really need a specific version, hard code it (this is rare but it happens).
+  3. If you need to know the current mermaid version, replace a mermaid code block with the word `info` and the version will be returned like [this](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiaW5mb1xuXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9fQ==)
+   

docs/n00b-overview.md

@@ -0,0 +1,27 @@
+# Overview for n00bs
+
+As a sysadmin I frequently have to document things, including drawing stuff.
+
+Using mermaid, I can type this as a comment in a script:
+
+```
+graph TD
+A[Client] --> B[Load Balancer]
+B --> C[Server01]
+B --> D[Server02]
+```
+
+And end up with this in the documentation:
+
+![Flowchart](./img/n00b-firstFlow.png)
+
+Most of the stuff I need to visualize can be scripted in a similar way, with a varitety of different symbols and chart types available. Since the diagram source is text based, it can be part of production scripts (and other pieces of code). So less time needs be spent on documenting as a separate task.
+
+Comparing with Visio and similar applications, mermaid is a really fast way to create good visualizations. This is especially apparent when editing a complex visualisation, this could take me hours in a desktop application but takes minutes (or even less if generation has been scripted) with mermaid.
+
+With mermaid I can spend a fraction of the time I normally would spend, and instead automate the diagram generation and end up saving even more time. I love it!
+
+
+However, a lot of the mermaid documentation is geared to professional frontend developers, presuming a skill set which I simply do not have.
+
+I needed a really basic instruction. And here it is.

docs/n00b-syntaxReference.md

@@ -0,0 +1,11 @@
+## Diagram syntax reference
+
+Having already [gotten started](n00b-gettingStarted.md), existing diagram syntax documentation was easy enough to follow even for a n00b like me..
+
+- [Flowchart](flowchart.md)
+- [Sequence diagram](sequenceDiagram.md)
+- [Class Diagram](classDiagram.md)
+- [State Diagram](stateDiagram.md)
+- [Gantt](gantt.md)
+- [Pie Chart](pie.md)
+

docs/sequenceDiagram.md

@@ -271,7 +271,16 @@ sequenceDiagram
 
 ```
 
+## Comments
 
+Comments can be entered within a sequence diagram, which will be ignored by the parser.  Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax
+
+```
+sequenceDiagram
+    Alice->>John: Hello John, how are you?
+    %% this is a comment
+    John-->>Alice: Great!
+```
 
 ## Styling
 

docs/stateDiagram.md

@@ -322,6 +322,21 @@ As in plantUml you can specify concurrency using the -- symbol.
         }
 ```
 
+## Comments
+
+Comments can be entered within a state diagram chart, which will be ignored by the parser.  Comments need to be on their own line, and must be prefaced with `%%` (double percent signs). Any text after the start of the comment to the next newline will be treated as a comment, including any diagram syntax
+
+```
+stateDiagram
+    [*] --> Still
+    Still --> [*]
+%% this is a comment
+    Still --> Moving
+    Moving --> Still %% another comment
+    Moving --> Crash
+    Crash --> [*]
+```
+
 ## Styling
 
 Styling of the a state diagram is done by defining a number of css classes.  During rendering these classes are extracted from the file located at src/themes/state.scss

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mermaid",
-  "version": "8.4.2",
+  "version": "8.4.3",
   "description": "Markdownish syntax for generating flowcharts, sequence diagrams, class diagrams, gantt charts and git graphs.",
   "main": "dist/mermaid.core.js",
   "keywords": [
@@ -49,18 +49,18 @@
     "@braintree/sanitize-url": "^3.1.0",
     "crypto-random-string": "^3.0.1",
     "d3": "^5.7.0",
-    "dagre-d3": "dagrejs/dagre-d3",
+    "dagre-d3-unofficial": "0.6.4",
     "dagre": "^0.8.4",
     "graphlib": "^2.1.7",
     "he": "^1.2.0",
     "lodash": "^4.17.11",
     "minify": "^4.1.1",
     "moment-mini": "^2.22.1",
-    "prettier": "^1.18.2",
     "scope-css": "^1.2.1"
   },
   "devDependencies": {
     "documentation": "^12.0.1",
+    "prettier": "^1.18.2",
     "eslint": "^6.3.0",
     "eslint-config-prettier": "^6.3.0",
     "eslint-plugin-prettier": "^3.1.0",

src/diagrams/class/classDiagram.spec.js

@@ -2,13 +2,13 @@
 import { parser } from './parser/classDiagram';
 import classDb from './classDb';
 
-describe('class diagram, ', function() {
-  describe('when parsing an info graph it', function() {
-    beforeEach(function() {
+describe('class diagram, ', function () {
+  describe('when parsing an info graph it', function () {
+    beforeEach(function () {
       parser.yy = classDb;
     });
 
-    it('should handle relation definitions', function() {
+    it('should handle relation definitions', function () {
       const str =
         'classDiagram\n' +
         'Class01 <|-- Class02\n' +
@@ -19,7 +19,8 @@ describe('class diagram, ', function() {
 
       parser.parse(str);
     });
-    it('should handle relation definition of different types and directions', function() {
+
+    it('should handle relation definition of different types and directions', function () {
       const str =
         'classDiagram\n' +
         'Class11 <|.. Class12\n' +
@@ -31,7 +32,7 @@ describe('class diagram, ', function() {
       parser.parse(str);
     });
 
-    it('should handle cardinality and labels', function() {
+    it('should handle cardinality and labels', function () {
       const str =
         'classDiagram\n' +
         'Class01 "1" *-- "many" Class02 : contains\n' +
@@ -66,7 +67,7 @@ describe('class diagram, ', function() {
       parser.parse(str);
     });
 
-    it('should handle method statements', function() {
+    it('should handle method statements', function () {
       const str =
         'classDiagram\n' +
         'Object <|-- ArrayList\n' +
@@ -76,7 +77,8 @@ describe('class diagram, ', function() {
 
       parser.parse(str);
     });
-    it('should handle parsing of method statements  grouped by brackets', function() {
+
+    it('should handle parsing of method statements  grouped by brackets', function () {
       const str =
         'classDiagram\n' +
         'class Dummy_Class {\n' +
@@ -92,7 +94,7 @@ describe('class diagram, ', function() {
       parser.parse(str);
     });
 
-    it('should handle parsing of separators', function() {
+    it('should handle parsing of separators', function () {
       const str =
         'classDiagram\n' +
         'class Foo1 {\n' +
@@ -124,14 +126,111 @@ describe('class diagram, ', function() {
 
       parser.parse(str);
     });
+
+    it('should handle a comment', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1 {\n' +
+        '%% Comment\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '}';
+
+      parser.parse(str);
+    });
+
+    it('should handle comments at the start', function () {
+      const str =
+        '%% Comment\n' +
+        'classDiagram\n' +
+        'class Class1 {\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '}';
+      parser.parse(str);
+    });
+
+    it('should handle comments at the end', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1 {\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '\n}' +
+        '%% Comment\n';
+
+      parser.parse(str);
+    });
+
+    it('should handle comments at the end no trailing newline', function () {
+      const str =
+      'classDiagram\n' +
+      'class Class1 {\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '}\n' +
+        '%% Comment';
+
+      parser.parse(str);
+    });
+
+    it('should handle a comment with multiple line feeds', function () {
+      const str =
+        'classDiagram\n\n\n' +
+        '%% Comment\n\n' +
+        'class Class1 {\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '}';
+
+      parser.parse(str);
+    });
+
+    it('should handle a comment with mermaid class diagram code in them', function () {
+      const str =
+        'classDiagram\n' +
+        '%% Comment Class01 <|-- Class02\n' +
+        'class Class1 {\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '}';
+
+      parser.parse(str);
+    });
+
+    it('should handle a comment inside brackets', function () {
+      const str =
+        'classDiagram\n' +
+        'class Class1 {\n' +
+        '%% Comment Class01 <|-- Class02\n' +
+        'int : test\n' +
+        'string : foo\n' +
+        'test()\n' +
+        'foo()\n' +
+        '}';
+
+      parser.parse(str);
+    });
   });
 
-  describe('when fetching data from an classDiagram graph it', function() {
-    beforeEach(function() {
+  describe('when fetching data from a classDiagram graph it', function () {
+    beforeEach(function () {
       parser.yy = classDb;
       parser.yy.clear();
     });
-    it('should handle relation definitions EXTENSION', function() {
+    it('should handle relation definitions EXTENSION', function () {
       const str = 'classDiagram\n' + 'Class01 <|-- Class02';
 
       parser.parse(str);
@@ -144,7 +243,8 @@ describe('class diagram, ', function() {
       expect(relations[0].relation.type2).toBe('none');
       expect(relations[0].relation.lineType).toBe(classDb.lineType.LINE);
     });
-    it('should handle relation definitions AGGREGATION and dotted line', function() {
+
+    it('should handle relation definitions AGGREGATION and dotted line', function () {
       const str = 'classDiagram\n' + 'Class01 o.. Class02';
 
       parser.parse(str);
@@ -157,7 +257,8 @@ describe('class diagram, ', function() {
       expect(relations[0].relation.type2).toBe('none');
       expect(relations[0].relation.lineType).toBe(classDb.lineType.DOTTED_LINE);
     });
-    it('should handle relation definitions COMPOSITION on both sides', function() {
+
+    it('should handle relation definitions COMPOSITION on both sides', function () {
       const str = 'classDiagram\n' + 'Class01 *--* Class02';
 
       parser.parse(str);
@@ -170,7 +271,8 @@ describe('class diagram, ', function() {
       expect(relations[0].relation.type2).toBe(classDb.relationType.COMPOSITION);
       expect(relations[0].relation.lineType).toBe(classDb.lineType.LINE);
     });
-    it('should handle relation definitions no types', function() {
+
+    it('should handle relation definitions no types', function () {
       const str = 'classDiagram\n' + 'Class01 -- Class02';
 
       parser.parse(str);
@@ -183,7 +285,8 @@ describe('class diagram, ', function() {
       expect(relations[0].relation.type2).toBe('none');
       expect(relations[0].relation.lineType).toBe(classDb.lineType.LINE);
     });
-    it('should handle relation definitions with type only on right side', function() {
+
+    it('should handle relation definitions with type only on right side', function () {
       const str = 'classDiagram\n' + 'Class01 --|> Class02';
 
       parser.parse(str);
@@ -197,7 +300,7 @@ describe('class diagram, ', function() {
       expect(relations[0].relation.lineType).toBe(classDb.lineType.LINE);
     });
 
-    it('should handle multiple classes and relation definitions', function() {
+    it('should handle multiple classes and relation definitions', function () {
       const str =
         'classDiagram\n' +
         'Class01 <|-- Class02\n' +
@@ -223,7 +326,7 @@ describe('class diagram, ', function() {
       expect(relations[3].relation.lineType).toBe(classDb.lineType.DOTTED_LINE);
     });
 
-    it('should handle class annotations', function() {
+    it('should handle class annotations', function () {
       const str = 'classDiagram\n' + 'class Class1\n' + '<<interface>> Class1';
       parser.parse(str);
 
@@ -234,7 +337,7 @@ describe('class diagram, ', function() {
       expect(testClass.annotations[0]).toBe('interface');
     });
 
-    it('should handle class annotations with members and methods', function() {
+    it('should handle class annotations with members and methods', function () {
       const str =
         'classDiagram\n' +
         'class Class1\n' +
@@ -250,7 +353,7 @@ describe('class diagram, ', function() {
       expect(testClass.annotations[0]).toBe('interface');
     });
 
-    it('should handle class annotations in brackets', function() {
+    it('should handle class annotations in brackets', function () {
       const str = 'classDiagram\n' + 'class Class1 {\n' + '<<interface>>\n' + '}';
       parser.parse(str);
 
@@ -261,7 +364,7 @@ describe('class diagram, ', function() {
       expect(testClass.annotations[0]).toBe('interface');
     });
 
-    it('should handle class annotations in brackets with members and methods', function() {
+    it('should handle class annotations in brackets with members and methods', function () {
       const str =
         'classDiagram\n' +
         'class Class1 {\n' +
@@ -278,7 +381,7 @@ describe('class diagram, ', function() {
       expect(testClass.annotations[0]).toBe('interface');
     });
 
-    it('should add bracket members in right order', function() {
+    it('should add bracket members in right order', function () {
       const str =
         'classDiagram\n' +
         'class Class1 {\n' +

src/diagrams/class/parser/classDiagram.jison

@@ -9,7 +9,7 @@
 %x string struct
 
 %%
-\%\%[^\n]*            /* do nothing */
+\%\%[^\n]*\n*           /* do nothing */
 \n+                   return 'NEWLINE';
 \s+                     /* skip whitespace */
 "classDiagram"          return 'CLASS_DIAGRAM';

src/diagrams/flowchart/flowChartShapes.js

@@ -1,4 +1,4 @@
-import dagreD3 from 'dagre-d3';
+import dagreD3 from 'dagre-d3-unofficial';
 
 function question(parent, bbox, node) {
   const w = bbox.width;

src/diagrams/flowchart/flowRenderer.js

@@ -6,11 +6,10 @@ import flow from './parser/flow';
 import { getConfig } from '../../config';
 
 const newDagreD3 = true;
-import dagreD3 from 'dagre-d3';
+import dagreD3 from 'dagre-d3-unofficial';
 // const newDagreD3 = false;
-// import dagreD3 from '../../../../dagre-d3-renderer/dist/dagre-d3.core.js';
 
-import addHtmlLabel from 'dagre-d3/lib/label/add-html-label.js';
+import addHtmlLabel from 'dagre-d3-unofficial/lib/label/add-html-label.js';
 import { logger } from '../../logger';
 import { interpolateToCurve } from '../../utils';
 import flowChartShapes from './flowChartShapes';

src/diagrams/flowchart/parser/flow-comments.spec.js

@@ -12,8 +12,8 @@ describe('[Comments] when parsing', () => {
     flow.parser.yy.clear();
   });
 
-  it('should handle a comments', function() {
-    const res = flow.parser.parse('graph TD;\n%% CComment\n A-->B;');
+  it('should handle comments', function() {
+    const res = flow.parser.parse('graph TD;\n%% Comment\n A-->B;');
 
     const vert = flow.parser.yy.getVertices();
     const edges = flow.parser.yy.getEdges();
@@ -27,7 +27,7 @@ describe('[Comments] when parsing', () => {
     expect(edges[0].text).toBe('');
   });
 
-  it('should handle comments a at the start', function() {
+  it('should handle comments at the start', function() {
     const res = flow.parser.parse('%% Comment\ngraph TD;\n A-->B;');
 
     const vert = flow.parser.yy.getVertices();
@@ -43,7 +43,7 @@ describe('[Comments] when parsing', () => {
   });
 
   it('should handle comments at the end', function() {
-    const res = flow.parser.parse('graph TD;\n A-->B\n %% Comment at the find\n');
+    const res = flow.parser.parse('graph TD;\n A-->B\n %% Comment at the end\n');
 
     const vert = flow.parser.yy.getVertices();
     const edges = flow.parser.yy.getEdges();
@@ -117,7 +117,7 @@ describe('[Comments] when parsing', () => {
     expect(edges[0].text).toBe('');
   });
 
-  it('should handle a comments with blank rows in-between', function() {
+  it('should handle a comment with blank rows in-between', function() {
     const res = flow.parser.parse('graph TD;\n\n\n %% Comment\n A-->B;');
 
     const vert = flow.parser.yy.getVertices();
@@ -132,7 +132,7 @@ describe('[Comments] when parsing', () => {
     expect(edges[0].text).toBe('');
   });
 
-  it('should handle a comments mermaid flowchart code in them', function() {
+  it('should handle a comment with mermaid flowchart code in them', function() {
     const res = flow.parser.parse(
       'graph TD;\n\n\n %% Test od>Odd shape]-->|Two line<br>edge comment|ro;\n A-->B;'
     );

src/diagrams/flowchart/parser/flow.jison

@@ -9,7 +9,7 @@
 %x string
 %x dir
 %%
-\%\%[^\n]*            /* do nothing */
+\%\%[^\n]*\n*           /* do nothing */
 ["]                     this.begin("string");
 <string>["]             this.popState();
 <string>[^"]*           return "STR";
@@ -460,13 +460,6 @@ text: textToken
 
 
 
-commentText: commentToken
-    {$$=$1;}
-    | commentText commentToken
-    {$$=$1+''+$2;}
-    ;
-
-
 keywords
     : STYLE | LINKSTYLE | CLASSDEF | CLASS | CLICK | GRAPH | DIR | subgraph | end | DOWN | UP;
 
@@ -516,8 +509,6 @@ linkStyleStatement
           {$$ = $1;yy.updateLinkInterpolate($3,$7);}
     ;
 
-commentStatement: PCT PCT commentText;
-
 numList: NUM
         {$$ = [$1]}
     | numList COMMA NUM
@@ -539,8 +530,6 @@ styleComponent: ALPHA | COLON | MINUS | NUM | UNIT | SPACE | HEX | BRKT | DOT |
 
 /* Token lists */
 
-commentToken   : textToken | graphCodeTokens ;
-
 textToken      : textNoTagsToken | TAGSTART | TAGEND | '=='  | '--' | PCT | DEFAULT;
 
 textNoTagsToken: alphaNumToken | SPACE | MINUS | keywords ;

src/mermaidAPI.js

@@ -686,7 +686,7 @@ export default mermaidAPI;
  * ## mermaidAPI configuration defaults
  * <pre>
  *
- * <script>
+ * &lt;script>
  *   var config = {
  *     theme:'default',
  *     logLevel:'fatal',
@@ -728,6 +728,6 @@ export default mermaidAPI;
  *     }
  *   };
  *   mermaid.initialize(config);
- * </script>
+ * &lt;/script>
  *</pre>
  */

webpack.config.base.js

@@ -1,10 +1,10 @@
-import path from 'path'
+import path from 'path';
 
 const amdRule = {
   parser: {
     amd: false // https://github.com/lodash/lodash/issues/3052
   }
-}
+};
 
 const jisonRule = {
   test: /\.jison$/,
@@ -14,7 +14,7 @@ const jisonRule = {
       'token-stack': true
     }
   }
-}
+};
 const jsRule = {
   test: /\.js$/,
   include: [
@@ -24,16 +24,13 @@ const jsRule = {
   use: {
     loader: 'babel-loader'
   }
-}
+};
 
-const scssRule = { // load scss to string
+const scssRule = {
+  // load scss to string
   test: /\.scss$/,
-  use: [
-    { loader: 'css-to-string-loader' },
-    { loader: 'css-loader' },
-    { loader: 'sass-loader' }
-  ]
-}
+  use: [{ loader: 'css-to-string-loader' }, { loader: 'css-loader' }, { loader: 'sass-loader' }]
+};
 
 export const jsConfig = () => {
   return {
@@ -43,7 +40,10 @@ export const jsConfig = () => {
       mermaid: './src/mermaid.js'
     },
     resolve: {
-      extensions: ['.wasm', '.mjs', '.js', '.json', '.jison']
+      extensions: ['.wasm', '.mjs', '.js', '.json', '.jison'],
+      alias: {
+        'dagre-d3': 'dagre-d3-unofficial'
+      }
     },
     node: {
       fs: 'empty' // jison generated code requires 'fs'
@@ -59,5 +59,5 @@ export const jsConfig = () => {
       rules: [amdRule, jsRule, scssRule, jisonRule]
     },
     devtool: 'source-map'
-  }
-}
+  };
+};

yarn.lock

@@ -3641,9 +3641,10 @@ d3@^5.12, d3@^5.7.0:
     d3-voronoi "1"
     d3-zoom "1"
 
-dagre-d3@dagrejs/dagre-d3:
-  version "0.6.4-pre"
-  resolved "https://codeload.github.com/dagrejs/dagre-d3/tar.gz/e1a00e5cb518f5d2304a35647e024f31d178e55b"
+dagre-d3-unofficial@0.6.4:
+  version "0.6.4"
+  resolved "https://registry.yarnpkg.com/dagre-d3-unofficial/-/dagre-d3-unofficial-0.6.4.tgz#c3d0c3993e53942b9ab977a98ac980b6e7c620eb"
+  integrity sha512-xihvMCALDS/X646WyqBSMN1kl7f0K1Urd42EKYgmyISwML1Bep1MCMm+2Q3TIJe6y8TwHKmW6oYXnP5I0J/LIg==
   dependencies:
     d3 "^5.12"
     dagre "^0.8.4"