diff --git a/README.md b/README.md
index 2a94d75f2..e5475f17e 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ __mermaid is a Javascript based diagramming and charting tool. It generates diag
 Check out the list of [Integrations and Usages of Mermaid](https://github.com/mermaid-js/mermaid/blob/develop/docs/integrations.md)
 
 For more information and help in getting started, please view our [documentation](http://mermaid-js.github.io/mermaid/) and start simplifying yours. Alternatively, you can also play with our [live editor](https://mermaidjs.github.io/mermaid-live-editor/).
-<!-- </Main description> --> 
+<!-- </Main description> -->
 
 :trophy: **Mermaid was nominated and won the [JS Open Source Awards (2019)](https://osawards.com/javascript/#nominees) 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.**
 
@@ -170,7 +170,7 @@ Crash --> [*]
 pie
 "Dogs" : 386
 "Cats" : 85
-"Rats" : 15 
+"Rats" : 15
 </pre></td>
     <td align="center">
         <img src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-pie.png" />
@@ -187,8 +187,13 @@ pie
 </tr>
 <!-- </Git> -->
 <!-- <Journey> -->
+<tr><td colspan=2 align="center">
+    <b>User Journey</b><br />
+    [<a href="http://mermaid-js.github.io/mermaid/#/userJourney">docs</a> - <a href="https://mermaidjs.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic3RhdGVEaWFncmFtXG4gICAgWypdIC0tPiBTdGlsbFxuICAgIFN0aWxsIC0tPiBbKl1cbiAgICBTdGlsbCAtLT4gTW92aW5nXG4gICAgTW92aW5nIC0tPiBTdGlsbFxuICAgIE1vdmluZyAtLT4gQ3Jhc2hcbiAgICBDcmFzaCAtLT4gWypdIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifX0">live editor</a>]
+</td></tr>
 <tr>
-  <td><pre>
+  <td>
+  <pre>
   journey
     title Hello
     section Go to work
@@ -200,14 +205,14 @@ pie
       Sit down: 3: Me
 </pre></td>
   <td align="center">
-    <img alt="User Journey Diagram" src="https://raw.githubusercontent.com/mermaid-js/mermaid/master/img/gray-journey.png" />
+    <img alt="User Journey Diagram" src="img/user-journey.png" />
   </td>
 </tr>
 <!-- </Journey> -->
 
 </table>
 
-## Related projects 
+## Related projects
 
 - [Command Line Interface](https://github.com/mermaid-js/mermaid.cli)
 - [Live Editor](https://github.com/mermaid-js/mermaid-live-editor)
diff --git a/cypress/integration/rendering/journey.spec.js b/cypress/integration/rendering/journey.spec.js
index 5fa822060..8bcf58412 100644
--- a/cypress/integration/rendering/journey.spec.js
+++ b/cypress/integration/rendering/journey.spec.js
@@ -16,16 +16,14 @@ section Order from website
     imgSnapshotTest(
       `
     journey
-      title Go shopping
-
-      section Get to the shops
-      Get car keys: Dad
-      Get into car: Dad, Mum, Child#1, Child#2
-      Drive to supermarket: Dad
-
-      section Do shopping
-      Do actual shop: Mum
-      Get in the way: Dad, Child#1, Child#2
+    title My working day
+    section Go to work
+      Make tea: 5: Me
+      Go upstairs: 3: Me
+      Do work: 1: Me, Cat
+    section Go home
+      Go downstairs: 5: Me
+      Sit down: 3: Me
       `,
       {}
     );
diff --git a/docs/mermaidAPI.md b/docs/mermaidAPI.md
index 6dd749e27..b5ab27571 100644
--- a/docs/mermaidAPI.md
+++ b/docs/mermaidAPI.md
@@ -209,6 +209,41 @@ This will display arrows that start and begin at the same node as right angles,
 This will show the node numbers
 **Default value false**.
 
+### actorFontSize
+
+This sets the font size of the actor's description
+**Default value 14**.
+
+### actorFontFamily
+
+This sets the font family of the actor's description
+**Default value "Open-Sans", "sans-serif"**.
+
+### noteFontSize
+
+This sets the font size of actor-attached notes.
+**Default value 14**.
+
+### noteFontFamily
+
+This sets the font family of actor-attached notes.
+**Default value "trebuchet ms", verdana, arial**.
+
+### noteAlign
+
+This sets the text alignment of actor-attached notes.
+**Default value center**.
+
+### messageFontSize
+
+This sets the font size of actor messages.
+**Default value 16**.
+
+### messageFontFamily
+
+This sets the font family of actor messages.
+**Default value "trebuchet ms", verdana, arial**.
+
 ## gantt
 
 The object containing configurations specific for gantt diagrams\*
@@ -263,6 +298,80 @@ The number of alternating section styles.
 Datetime format of the axis. This might need adjustment to match your locale and preferences
 **Default value '%Y-%m-%d'**.
 
+## journey
+
+The object containing configurations specific for sequence diagrams
+
+### diagramMarginX
+
+margin to the right and left of the sequence diagram.
+**Default value 50**.
+
+### diagramMarginY
+
+margin to the over and under the sequence diagram.
+**Default value 10**.
+
+### actorMargin
+
+Margin between actors.
+**Default value 50**.
+
+### width
+
+Width of actor boxes
+**Default value 150**.
+
+### height
+
+Height of actor boxes
+**Default value 65**.
+
+### boxMargin
+
+Margin around loop boxes
+**Default value 10**.
+
+### boxTextMargin
+
+margin around the text in loop/alt/opt boxes
+**Default value 5**.
+
+### noteMargin
+
+margin around notes.
+**Default value 10**.
+
+### messageMargin
+
+Space between messages.
+**Default value 35**.
+
+### messageAlign
+
+Multiline message alignment. Possible values are:
+
+-   left
+-   center **default**
+-   right
+
+### bottomMarginAdj
+
+Depending on css styling this might need adjustment.
+Prolongs the edge of the diagram downwards.
+**Default value 1**.
+
+### useMaxWidth
+
+when this flag is set the height and width is set to 100% and is then scaling with the
+available space if not the absolute space required is used.
+**Default value true**.
+
+### rightAngles
+
+This will display arrows that start and begin at the same node as right angles, rather than a curve
+**Default value false**.
+
 ## er
 
 The object containing configurations specific for entity relationship diagrams
diff --git a/img/user-journey.png b/img/user-journey.png
new file mode 100644
index 000000000..02368521a
Binary files /dev/null and b/img/user-journey.png differ