diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 8bf4b1d33..16dd3de63 100644 --- a/docs/_sidebar.md +++ b/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) \ No newline at end of file + - [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) diff --git a/docs/img/n00b-Confluence1.png b/docs/img/n00b-Confluence1.png new file mode 100644 index 000000000..106b7dca6 Binary files /dev/null and b/docs/img/n00b-Confluence1.png differ diff --git a/docs/img/n00b-Confluence2.png b/docs/img/n00b-Confluence2.png new file mode 100644 index 000000000..2b7ed4362 Binary files /dev/null and b/docs/img/n00b-Confluence2.png differ diff --git a/docs/img/n00b-Confluence3.png b/docs/img/n00b-Confluence3.png new file mode 100644 index 000000000..c2c4cc763 Binary files /dev/null and b/docs/img/n00b-Confluence3.png differ diff --git a/docs/img/n00b-Confluence4.png b/docs/img/n00b-Confluence4.png new file mode 100644 index 000000000..63b460070 Binary files /dev/null and b/docs/img/n00b-Confluence4.png differ diff --git a/docs/img/n00b-firstFlow.png b/docs/img/n00b-firstFlow.png new file mode 100644 index 000000000..c10174151 Binary files /dev/null and b/docs/img/n00b-firstFlow.png differ diff --git a/docs/img/n00b-liveEditor.png b/docs/img/n00b-liveEditor.png new file mode 100644 index 000000000..071a44fca Binary files /dev/null and b/docs/img/n00b-liveEditor.png differ diff --git a/docs/mermaidAPI.md b/docs/mermaidAPI.md index 8152b188f..ce11e5c58 100644 --- a/docs/mermaidAPI.md +++ b/docs/mermaidAPI.md @@ -275,7 +275,7 @@ mermaidAPI.initialize({ 
 
-
-
+</script>
[1]: https://github.com/knsv/mermaid/blob/master/docs/mermaidAPI.md#render diff --git a/docs/n00b-advanced.md b/docs/n00b-advanced.md new file mode 100644 index 000000000..407be8c08 --- /dev/null +++ b/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 + + + +``` +The actual mermaid file could for example look like this: + +``` +mermaid content... +``` +--- + +## mermaid configuration options + +... diff --git a/docs/n00b-gettingStarted.md b/docs/n00b-gettingStarted.md new file mode 100644 index 000000000..96cd576c9 --- /dev/null +++ b/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 `` 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 ` + +``` + +2. The embedded mermaid code is similarly placed in a `
` tag: + +``` + + Here is a mermaid diagram: +
+ graph TD + A[Client] --> B[Load Balancer] + B --> C[Server01] + B --> D[Server02] +
+ +``` + +3. When initializing mermaid using `mermaid.initialize()`, mermaid takes all the `
` tags it can find in the html body and starts to render them one by one. This is done like so: + +``` + + + +``` + +*Finally* +4. Putting the three steps together is as simple as: +``` + + + + + + Here is one mermaid diagram: +
+ graph TD + A[Client] --> B[Load Balancer] + B --> C[Server1] + B --> D[Server2] +
+ + And here is another: +
+ graph TD + A[Client] -->|tcp_123| B(Load Balancer) + B -->|tcp_456| C[Server1] + B -->|tcp_456| D[Server2] +
+ + +``` +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> * */ diff --git a/webpack.config.base.js b/webpack.config.base.js index 0a02420a3..dcde900d4 100644 --- a/webpack.config.base.js +++ b/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' - } -} + }; +}; diff --git a/yarn.lock b/yarn.lock index 75ff603e3..e6377b0e5 100644 --- a/yarn.lock +++ b/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"