New version of docs

docs/usage.md

@@ -0,0 +1,194 @@
+---
+title: Usage
+order: 1
+---
+#Installation
+
+Either use the npm or bower package managers as per below:
+
+```
+bower install mermaid --save-dev
+```
+
+```
+npm install mermaid --save-dev
+```
+
+Or download javascript files:
+
+* [mermaid including dependencies](https://cdn.rawgit.com/knsv/mermaid/0.d.0/dist/mermaid.min.js)
+
+
+There are some bundles to choose from:
+* mermaid.js, mermaid.min.js This bundle contains everything you need to run mermaid
+* mermaid.slim.js, mermaid.slim.min.js This bundle does not contain d3 which is usefull for sites that already have d3 in place
+* mermaidAPI.js, mermaidAPI.min.js, This bundle does not contain the web integration provided in the other packages but has a render function instead returns svg code.
+
+
+** Important: **
+> It's best to use a specific tag or commit hash in the URL (not a branch). Files are cached permanently after the first request.
+
+Read more about that at [https://rawgit.com/](https://rawgit.com/)
+
+# Usage
+
+Include mermaid on your web page:
+
+```
+<script src="mermaid.min.js"></script>
+<script>mermaid.initialize({startOnLoad:true});</script>
+
+```
+
+Further down on your page mermaid will look for tags with ```class="mermaid"```. From these tags mermaid will try to
+read the chart definiton which will be replaced with the svg chart.
+
+
+A chart defined like this:
+
+```
+<div class="mermaid">
+    CHART DEFINITION GOES HERE
+</div>
+
+```
+
+Would end up like this:
+```
+<div class="mermaid" id="mermaidChart0">
+    <svg>
+        Chart ends up here
+    </svg>
+</div>
+
+```
+An id is also added to mermaid tags without id.
+
+## Calling `mermaid.init`
+By default, `mermaid.init` will be called when the document is ready, finding all elements with
+`class="mermaid"`. If you are adding content after mermaid is loaded, or otherwise need
+finer-grained control of this behavior, you can call `init` yourself with:
+- a configuration object
+- some nodes, as
+  - a node
+  - an a array-like of nodes
+  - or W3C selector that will find your nodes
+
+Example:
+```
+mermaid.init({noteMargin: 10}, ".someOtherClass");
+```
+Or with no config object, and a jQuery selection:
+```
+mermaid.init(undefined, $("#someId .yetAnotherClass"));
+```
+
+#Usage with browserify
+Minimalistic javascript:
+```
+
+mermaid = require('mermaid');
+```
+
+#API usage
+Include mermaid on your web page:
+
+```
+<script src="mermaidAPI.js"></script>
+
+<script>
+    mermaidAPI.initialize({
+        startOnLoad:false
+        });
+    $(function(){
+        var graphDefinition = 'graph TB\na-->b';
+        var graph = mermaidAPI.render(graphDefinition);
+        $("#graphDiv").html(graph);
+    });
+</script>
+```
+#Sample API usage with browserify
+```
+$ = require('jquery');
+mermaidAPI = require('mermaid').mermaidAPI;
+mermaidAPI.initialize({
+    startOnLoad:false
+    });
+
+$(function(){
+    var graphDefinition = 'graph TB\na-->b';
+    var cb = function(html){
+	    console.log(html);
+    }
+    mermaidAPI.render('id1',graphDefinition,cb);
+});
+```
+
+# Example of marked renderer
+
+This is the renderer used for transforming the documentation from markdown to html with mermaid diagrams in the html.
+
+```
+    var renderer = new marked.Renderer();
+    renderer.code = function (code, language) {
+        if(code.match(/^sequenceDiagram/)||code.match(/^graph/)){
+            return '<div class="mermaid">'+code+'</div>';
+        }
+        else{
+            return '<pre><code>'+code+'</code></pre>';
+        }
+    };
+```
+
+Another example in coffeescript that also includes the mermaid script tag into the generated markup.
+```
+marked = require 'marked'
+
+module.exports = (options) ->
+  hasMermaid = false
+  renderer = new marked.Renderer()
+  renderer.defaultCode = renderer.code
+  renderer.code = (code, language) ->
+    if language is 'mermaid'
+      html = ''
+      if not hasMermaid
+        hasMermaid = true
+        html += '<script src="'+options.mermaidPath+'"></script>'
+      html + '<div class="mermaid">'+code+'</div>'
+    else
+      @defaultCode(code, language)
+
+  renderer
+  ```
+
+## Advanced usage
+
+**Error handling**
+
+When the parser encounters invalid syntax the **mermaid.parseError** function is called. It is possible to override this
+function in order to handle the error in an application specific way.
+
+**Parsing text without rendering**
+
+It is also possible to validate the syntax before rendering in order to streamline the user experience. The function
+**mermaid.parse(txt)** takes a text string as an argument and returns true if the text is syntactically correct and
+false if it is not. The parseError function will be called when the parse function returns false.
+
+The code-example below in meta code illustrates how this could work:
+
+```js
+
+mermaid.parseError = function(err,hash){
+    displayErrorInGui(err);
+};
+
+var textFieldUpdated = function(){
+    var textStr = getTextFromFormField('code');
+
+    if(mermaid.parse(textStr)){
+        reRender(textStr)
+    }
+};
+
+bindEventHandler('change', 'code', textFieldUpdated);
+```