From cd8b7e5528536a0773428fa1b62469e2668f1501 Mon Sep 17 00:00:00 2001 From: NeilCuzon <58763315+NeilCuzon@users.noreply.github.com> Date: Fri, 21 Feb 2020 21:11:21 -0800 Subject: [PATCH 01/25] Update README.md Hi, I love your program and how it reimagines the whole dynamic of creating diagrams and graphs, I also like the wit of the documentation, but I had some small trouble in initially figuring out what the application was about. I propose a few line changes to clarify the purpose of the application and an additional a link to the syntax section of docs to hopefully decrease the friction and increase the interest in using the product. I changed: -"__mermaid is a Javascript based diagramming and charting tool. It generates diagrams flowcharts and more, using markdown-inspired text for ease and speed.__" and I added: -"__The following are some examples of the diagrams, charts and graphs that can be made using mermaid and the Markdown-inspired text specific to it. Click here jump into the [text syntax](https://mermaid-js.github.io/mermaid/#/n00b-syntaxReference).__" More power to you and your team. -Neil --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d09567c524..5bb69e6b3c 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,14 @@ # mermaid [![Build Status](https://travis-ci.org/mermaid-js/mermaid.svg?branch=master)](https://travis-ci.org/mermaid-js/mermaid) [![NPM](https://img.shields.io/npm/v/mermaid)](https://www.npmjs.com/package/mermaid) [![Coverage Status](https://coveralls.io/repos/github/mermaid-js/mermaid/badge.svg?branch=master)](https://coveralls.io/github/mermaid-js/mermaid?branch=master) [![Join our Slack!](https://img.shields.io/static/v1?message=join%20chat&color=9cf&logo=slack&label=slack)](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) [![This project is using Percy.io for visual regression testing.](https://percy.io/static/images/percy-badge.svg)](https://percy.io/Mermaid/mermaid) -__Generate diagrams, charts, graphs or flows from markdown-like text via javascript.__ -See our [documentation](http://mermaid-js.github.io/mermaid/) and start simplifying yours. Play in our [live editor](https://mermaidjs.github.io/mermaid-live-editor/) or jump straight to the [installation and usage](http://mermaid-js.github.io/mermaid/#/usage). +__mermaid is a Javascript based diagramming and charting tool. It generates diagrams flowcharts and more, using markdown-inspired text for ease and speed.__ + +For more information and help in gettin started, please view our [documentation](http://mermaid-js.github.io/mermaid/) and start simplifying yours. Play with our [live editor](https://mermaidjs.github.io/mermaid-live-editor/) or jump straight to the [installation and usage](http://mermaid-js.github.io/mermaid/#/usage). :trophy: _"The most exciting use of technology"_ - [JS Open Source Awards (2019)](https://osawards.com/javascript/#nominees) +__The following are some examples of the diagrams, charts and graphs that can be made using mermaid and the Markdown-inspired text specific to it. Click here jump into the [text syntax](https://mermaid-js.github.io/mermaid/#/n00b-syntaxReference).__
From 17f99aeed82c8fce6a3dc680148f43d867ed25b3 Mon Sep 17 00:00:00 2001 From: NeilCuzon <58763315+NeilCuzon@users.noreply.github.com> Date: Sat, 22 Feb 2020 19:21:37 -0800 Subject: [PATCH 02/25] Updated n00b-gettingStarted.md this section had some outdated info regarding the live editor and its capabilities. -replaced and outdated screenshot -edited the documentation to make it a little more n00b friendly. -added a link to the Atom mermaid plugin -Neil --- docs/n00b-gettingStarted.md | 70 +++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 30 deletions(-) diff --git a/docs/n00b-gettingStarted.md b/docs/n00b-gettingStarted.md index 96cd576c9d..6619ebacf1 100644 --- a/docs/n00b-gettingStarted.md +++ b/docs/n00b-gettingStarted.md @@ -1,42 +1,45 @@ -# A more basic getting started +# A basic Walkthrough for beginners -Writing mermaid code is simple. +Creating diagrams and charts, using 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. +But how is the code turned into a diagram in a web page? This is done with the use of a mermaid renderer. -Thankfully the mermaid renderer is very accessible, in essence it is a javascript. +Thankfully the mermaid renderer is very accessible, in essence it is a piece of javascript that can be called. -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 +Most widely used web browsers, such as Firefox, Chrome and Safari, can render mermaid, Internet Explorer however 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 +# For beginners, there are three relatively easy ways you can use mermaid: +1. Using the mermaid [live editor](https://mermaid-js.github.io/mermaid-live-editor/) +2. Using a mermaid plugin, such as that for Confluence or [Atom](https://atom.io/packages/atom-mermaid). +3. Calling mermaid with HTML, deployed in a friendly browser. -Following either of these examples, you can get started with converting your own mermaid code into web diagrams. +# Following either of these examples, you can get started with creating your own diagrams using mermaid code. -## the mermaid live editor +## 1. 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. +In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it. 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. +It is also the easiest way to develop diagrams. You can also click "Copy Markdown" to copy the markdown code for the diagram, that can then be pasted directly into your documentation. +You can also copy the code from the code section and paste it into either a mermaid plugin or in inside an html file, which will be taught in numbers 2 and 3. -![Flowchart](./img/n00b-liveEditor.png) +![Flowchart](./img/liveEditor-options.png.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 +## 2. Using mermaid plugins Thanks to the growing popularity of mermaid, many plugins already exist which incorporate a mermaid renderer. +One example is the [Atom plugin](https://atom.io/packages/atom-mermaid) for mermaid. -One example is the [Atlassian Confluence mermaid plugin](https://marketplace.atlassian.com/apps/1214124/mermaid-plugin-for-confluence?hosting=server&tab=overview) +Another 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. +# Here is a step by step process for using the mermaid-Confluence plugin: --- @@ -64,24 +67,30 @@ When the mermaid plugin is installed on a Confluence server, one can insert a me --- -## mermaid using any web server (or just a browser) +## 3. 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. +This method 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 program (like Notepad++) that can generate an html file, which is then deployed 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! + +# Here are instructions for creating an html file with mermaid code: +# Note that all this is written in the html `` section of the web page. + +When writing the html file, we give the web browser three instructions inside the html code: +a. A reference for fetching the online mermaid renderer, which is written in Javascript. +b. The mermaid code for the diagram we want to create. +c. The `mermaid.initialize()` command to start the rendering process. -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 `