Compare commits

..

60 Commits
8.4.2 ... 8.4.3

Author SHA1 Message Date
Knut Sveidqvist
cb07a729e5 Merge pull request #1098 from mermaid-js/feature/1053_documentation-update
Feature/1053 documentation update
2019-12-01 00:42:41 +01:00
Nacho
02d5143ff2 Merge pull request #1095 from mermaid-js/fixes/readme-uris
Absolute URIs in readme images
2019-11-28 08:28:12 -05:00
Erik Ellingsen
d9c92b2c6d syntax error 2019-11-28 13:22:02 +01:00
Erik Ellingsen
27ac9bbaf3 polish 2019-11-28 13:14:29 +01:00
Erik Ellingsen
11cdd393f2 Knuts comments 2019-11-28 13:13:26 +01:00
Erik Ellingsen
1ca8578035 polish 2019-11-28 13:07:14 +01:00
Erik Ellingsen
2516718882 Clarification 2019-11-28 13:06:16 +01:00
Erik Ellingsen
5283314c4f Polish 2019-11-28 13:03:58 +01:00
Erik Ellingsen
dcae8da0d1 Better header 2019-11-28 13:01:24 +01:00
Erik Ellingsen
34f2a1a02f polish 2019-11-28 13:00:12 +01:00
Erik Ellingsen
ee5a68a23c Better intro 2019-11-28 12:59:34 +01:00
Erik Ellingsen
6c706ccd9f Diagram references 2019-11-28 12:57:55 +01:00
Erik Ellingsen
94106f5825 Added syntax reference link 2019-11-28 12:53:33 +01:00
Erik Ellingsen
72ab2b8011 Added coming soon 2019-11-28 12:44:37 +01:00
Erik Ellingsen
8978ab5917 Links added 2019-11-28 12:43:55 +01:00
Erik Ellingsen
94577316f9 Drafting advanced usage 2019-11-28 12:38:42 +01:00
Erik Ellingsen
91650fb052 Script bug and clarifications 2019-11-28 12:34:26 +01:00
Knut Sveidqvist
e9aa037230 Removed loggin 2019-11-27 20:15:21 +01:00
Nacho
871e6f691c Absolute URIs in readme images 2019-11-27 14:12:34 -05:00
Knut Sveidqvist
fe60836a89 Added analytics for docs 2019-11-27 20:08:54 +01:00
Nacho
e461b57a48 Merge pull request #1075 from jbednar/master
Fixed typos
2019-11-19 08:33:22 -05:00
James A. Bednar
eca9d49575 Fixed typos 2019-11-18 09:32:39 -06:00
Erik Ellingsen
8b5f8b0cb4 grammar 2019-11-08 10:36:41 +01:00
Erik Ellingsen
d0c9b5e98f grammar 2019-11-08 10:35:38 +01:00
erelling
7dead548f3 Update n00b-gettingStarted.md 2019-11-08 01:59:44 +01:00
erelling
8db46ff762 Update n00b-overview.md 2019-11-08 01:57:18 +01:00
erelling
93f54a997a Update n00b-gettingStarted.md 2019-11-08 01:53:58 +01:00
erelling
1353491952 Update n00b-gettingStarted.md 2019-11-08 01:47:34 +01:00
erelling
00802ffe7a Update n00b-gettingStarted.md 2019-11-08 01:45:29 +01:00
erelling
78e556aaf7 Update n00b-gettingStarted.md 2019-11-08 01:44:12 +01:00
erelling
e34988d65a Update n00b-gettingStarted.md 2019-11-08 01:32:09 +01:00
erelling
07f5c7c89c Update n00b-gettingStarted.md 2019-11-08 01:31:21 +01:00
erelling
7319d8941a Update n00b-gettingStarted.md 2019-11-08 01:25:41 +01:00
erelling
3d7933135b Update n00b-gettingStarted.md 2019-11-08 01:23:33 +01:00
erelling
a778472461 Update n00b-gettingStarted.md 2019-11-08 01:21:50 +01:00
erelling
cbe2a7446d Update n00b-gettingStarted.md 2019-11-08 01:17:21 +01:00
erelling
8251dc5cd1 Update n00b-gettingStarted.md 2019-11-08 01:16:16 +01:00
erelling
5a4103a248 Update n00b-gettingStarted.md 2019-11-08 01:15:41 +01:00
erelling
d7996f5c1a Update n00b-gettingStarted.md 2019-11-08 01:14:38 +01:00
erelling
db4229f033 Update n00b-gettingStarted.md 2019-11-08 01:13:14 +01:00
erelling
e103664963 Update n00b-gettingStarted.md 2019-11-08 01:12:14 +01:00
erelling
fbf3936ddc Update n00b-overview.md 2019-11-08 01:11:07 +01:00
erelling
62d03f1976 Update n00b-overview.md 2019-11-08 01:10:24 +01:00
erelling
f3ea159c6b Update n00b-overview.md 2019-11-08 01:08:14 +01:00
erelling
3c99294a3a Update n00b-overview.md 2019-11-08 01:06:57 +01:00
erelling
7a2a8cffbb Update n00b-overview.md 2019-11-08 01:06:20 +01:00
erelling
6d90f87b2f Update n00b-overview.md 2019-11-08 01:04:21 +01:00
erelling
f506d24a82 Update n00b-overview.md 2019-11-08 01:01:37 +01:00
Erik Ellingsen
ddb0d23ca7 grammar 2019-11-08 00:04:53 +01:00
Erik Ellingsen
763be9bb95 better instruction 2019-11-07 23:52:47 +01:00
Erik Ellingsen
77109144e7 grammar 2019-11-07 23:47:34 +01:00
Erik Ellingsen
840e7bd985 clarification 2019-11-07 23:47:08 +01:00
Erik Ellingsen
a6c12f4b25 clarification 2019-11-07 23:46:30 +01:00
Erik Ellingsen
e8e9a4d07b simplification 2019-11-07 23:45:23 +01:00
Erik Ellingsen
ba00182ce4 Clarification 2019-11-07 23:44:47 +01:00
Erik Ellingsen
2ad78ee3b8 grammar 2019-11-07 23:42:56 +01:00
Erik Ellingsen
4995d59499 Knuts comments 2019-11-07 23:42:07 +01:00
Erik Ellingsen
d58ef7aa36 Removed redundant heading 2019-11-07 23:40:13 +01:00
Erik Ellingsen
dc59632fb3 Polishing 2019-11-07 23:37:46 +01:00
Erik Ellingsen
1542e15a1b Introduction and getting started howtos 2019-11-07 23:15:53 +01:00
17 changed files with 293 additions and 19 deletions

View File

@@ -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> -->

View File

@@ -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>

View File

@@ -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.

View File

@@ -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)
- [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)

Binary file not shown.

After

Width:  |  Height:  |  Size: 71 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 49 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/img/n00b-firstFlow.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 111 KiB

View File

@@ -8,7 +8,19 @@
<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>
(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>
<!-- -->

View File

@@ -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

21
docs/n00b-advanced.md Normal file
View File

@@ -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
...

154
docs/n00b-gettingStarted.md Normal file
View File

@@ -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==)

27
docs/n00b-overview.md Normal file
View File

@@ -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.

View File

@@ -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)

View File

@@ -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>
*/