diff --git a/cypress/platform/user-journey.html b/cypress/platform/user-journey.html
index 2fcd48046..8c4a7b63b 100644
--- a/cypress/platform/user-journey.html
+++ b/cypress/platform/user-journey.html
@@ -33,7 +33,7 @@
     <script>
       mermaid.initialize({
         theme: 'forest',
-        logLevel: 1,
+        logLevel: 3,
         journey: { taskMargin: 30 },
       });
     </script>
diff --git a/docs/mermaidAPI.md b/docs/mermaidAPI.md
index 2469edd12..6dd749e27 100644
--- a/docs/mermaidAPI.md
+++ b/docs/mermaidAPI.md
@@ -263,84 +263,14 @@ 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
 
+### diagramPadding
+
+The amount of padding around the diagram as a whole so that embedded diagrams have margins, expressed in pixels
+
 ### layoutDirection
 
 Directional bias for layout of entities. Can be either 'TB', 'BT', 'LR', or 'RL',
@@ -348,15 +278,15 @@ where T = top, B = bottom, L = left, and R = right.
 
 ### minEntityWidth
 
-The mimimum width of an entity box
+The mimimum width of an entity box, expressed in pixels
 
 ### minEntityHeight
 
-The minimum height of an entity box
+The minimum height of an entity box, expressed in pixels
 
 ### entityPadding
 
-The minimum internal padding between the text in an entity box and the enclosing box borders
+The minimum internal padding between the text in an entity box and the enclosing box borders, expressed in pixels
 
 ### stroke
 
@@ -366,12 +296,6 @@ Stroke color of box edges and lines
 
 Fill color of entity boxes
 
-### fillOpacity
-
-Opacity of entity boxes - if you want to see how the crows feet
-retain their elegant joins to the boxes regardless of the angle of incidence
-then override this to something less than 100%
-
 ### fontSize
 
 Font size
@@ -431,6 +355,7 @@ mermaidAPI.initialize({
       boxTextMargin:5,
       noteMargin:10,
       messageMargin:35,
+      messageAlign:'center',
       mirrorActors:true,
       bottomMarginAdj:1,
       useMaxWidth:true,
diff --git a/docs/user-journey.md b/docs/user-journey.md
new file mode 100644
index 000000000..2446c6db0
--- /dev/null
+++ b/docs/user-journey.md
@@ -0,0 +1,23 @@
+# User Journey Diagram
+
+> User journeys describe at a high level of detail exactly what steps different users take to complete a specific task within a system, application or website. This technique shows the current (as-is) user workflow, and reveals areas of improvement for the to-be workflow. (Wikipedia)
+
+Mermaid can render user journey diagrams:
+
+```markdown
+journey
+    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: 5: Me
+```
+
+Each user journey is split into sections, these describe the part of the task
+the user is trying to complete.
+
+Tasks syntax is `Task name: <score>: <comma separated list of actors>`
+
diff --git a/src/mermaidAPI.js b/src/mermaidAPI.js
index 9dd4c77ab..fabc9e096 100644
--- a/src/mermaidAPI.js
+++ b/src/mermaidAPI.js
@@ -45,6 +45,9 @@ import pieDb from './diagrams/pie/pieDb';
 import erDb from './diagrams/er/erDb';
 import erParser from './diagrams/er/parser/erDiagram';
 import erRenderer from './diagrams/er/erRenderer';
+import journeyParser from './diagrams/user-journey/parser/journey';
+import journeyDb from './diagrams/user-journey/journeyDb';
+import journeyRenderer from './diagrams/user-journey/journeyRenderer';
 
 const themes = {};
 for (const themeName of ['default', 'forest', 'dark', 'neutral']) {
@@ -337,6 +340,92 @@ const config = {
      */
     axisFormat: '%Y-%m-%d'
   },
+  /**
+   * The object containing configurations specific for sequence diagrams
+   */
+  journey: {
+    /**
+     * margin to the right and left of the sequence diagram.
+     * **Default value 50**.
+     */
+    diagramMarginX: 50,
+
+    /**
+     * margin to the over and under the sequence diagram.
+     * **Default value 10**.
+     */
+    diagramMarginY: 10,
+
+    /**
+     * Margin between actors.
+     * **Default value 50**.
+     */
+    actorMargin: 50,
+
+    /**
+     * Width of actor boxes
+     * **Default value 150**.
+     */
+    width: 150,
+
+    /**
+     * Height of actor boxes
+     * **Default value 65**.
+     */
+    height: 65,
+
+    /**
+     * Margin around loop boxes
+     * **Default value 10**.
+     */
+    boxMargin: 10,
+
+    /**
+     * margin around the text in loop/alt/opt boxes
+     * **Default value 5**.
+     */
+    boxTextMargin: 5,
+
+    /**
+     * margin around notes.
+     * **Default value 10**.
+     */
+    noteMargin: 10,
+
+    /**
+     * Space between messages.
+     * **Default value 35**.
+     */
+    messageMargin: 35,
+
+    /**
+     * Multiline message alignment. Possible values are:
+     *   * left
+     *   * center **default**
+     *   * right
+     */
+    messageAlign: 'center',
+
+    /**
+     * Depending on css styling this might need adjustment.
+     * Prolongs the edge of the diagram downwards.
+     * **Default value 1**.
+     */
+    bottomMarginAdj: 1,
+
+    /**
+     * 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**.
+     */
+    useMaxWidth: true,
+
+    /**
+     * This will display arrows that start and begin at the same node as right angles, rather than a curve
+     * **Default value false**.
+     */
+    rightAngles: false
+  },
   class: {},
   git: {},
   state: {
@@ -465,6 +554,11 @@ function parse(text) {
       parser = erParser;
       parser.parser.yy = erDb;
       break;
+    case 'journey':
+      logger.debug('Journey');
+      parser = journeyParser;
+      parser.parser.yy = journeyDb;
+      break;
   }
 
   parser.parser.yy.parseError = (str, hash) => {
@@ -696,6 +790,10 @@ const render = function(id, _txt, cb, container) {
       erRenderer.setConf(config.er);
       erRenderer.draw(txt, id, pkg.version);
       break;
+    case 'journey':
+      journeyRenderer.setConf(config.journey);
+      journeyRenderer.draw(txt, id, pkg.version);
+      break;
   }
 
   d3.select(`[id="${id}"]`)
diff --git a/src/utils.js b/src/utils.js
index 823191ffc..b1073952f 100644
--- a/src/utils.js
+++ b/src/utils.js
@@ -59,6 +59,10 @@ export const detectType = function(text) {
     return 'er';
   }
 
+  if (text.match(/^\s*journey/)) {
+    return 'journey';
+  }
+
   return 'flowchart';
 };