diff --git a/packages/mermaid/src/docs/syntax/gantt.md b/packages/mermaid/src/docs/syntax/gantt.md
index a0cebc560df..fb8b296baef 100644
--- a/packages/mermaid/src/docs/syntax/gantt.md
+++ b/packages/mermaid/src/docs/syntax/gantt.md
@@ -29,7 +29,6 @@ gantt
 ```
 
 ## Syntax
-
 ```mermaid-example
 gantt
     dateFormat  YYYY-MM-DD
@@ -63,7 +62,30 @@ gantt
     Add another diagram to demo page    :48h
 ```
 
-It is possible to set multiple dependencies separated by space:
+Tasks are by default sequential. A task start date defaults to the end date of the preceding task.
+
+A colon, `:`, separates the task title from its metadata.
+Metadata items are separated by a comma, `,`. Valid tags are `active`, `done`, `crit`, and `milestone`. Tags are optional, but if used, they must be specified first.
+After processing the tags, the remaining metadata items are interpreted as follows:
+
+1. If a single item is specified, it determines when the task ends. It can either be a specific date/time or a duration. If a duration is specified, it is added to the start date of the task to determine the end date of the task, taking into account any exclusions.
+2. If two items are specified, the last item is interpreted as in the previous case. The first item can either specify an explicit start date/time (in the format specified by `dateFormat`) or reference another task using `after <otherTaskID> [[otherTaskID2 [otherTaskID3]]...]`. In the latter case, the start date of the task will be set according to the latest end date of any referenced task.
+3. If three items are specified, the last two will be interpreted as in the previous case. The first item will denote the ID of the task, which can be referenced using the `later <taskID>` syntax.
+
+| Metadata syntax                            | Start date                                          | End date                                    | ID       |
+|--------------------------------------------|-----------------------------------------------------|---------------------------------------------|----------|
+| `<taskID>, <startDate>, <endDate>`         | `startdate` as interpreted using `dateformat`       | `endDate` as interpreted using `dateformat` | `taskID` |
+| `<taskID>, <startDate>, <length>`          | `startdate` as interpreted using `dateformat`       | Start date + `length`                       | `taskID` |
+| `<taskID>, after <otherTaskId>, <endDate>` | End date of previously specified task `otherTaskID` | `endDate` as interpreted using `dateformat` | `taskID` |
+| `<taskID>, after <otherTaskId>, <length>`  | End date of previously specified task `otherTaskID` | Start date + `length`                       | `taskID` |
+| `<startDate>, <endDate>`                   | `startdate` as interpreted using `dateformat`       | `enddate` as interpreted using `dateformat` | n/a      |
+| `<startDate>, <length>`                    | `startdate` as interpreted using `dateformat`       | Start date + `length`                       | n/a      |
+| `after <otherTaskID>, <endDate>`           | End date of previously specified task `otherTaskID` | `enddate` as interpreted using `dateformat` | n/a      |
+| `after <otherTaskID>, <length>`            | End date of previously specified task `otherTaskID` | Start date + `length`                       | n/a      |
+| `<endDate>`                                | End date of preceding task                          | `enddate` as interpreted using `dateformat` | n/a      |
+| `<length>`                                 | End date of preceding task                          | Start date + `length`                       | n/a      |
+
+For simplicity, the table does not show the use of multiple tasks listed with the `after` keyword. Here is an example of how to use it and how it's interpreted:
 
 ```mermaid-example
 gantt
@@ -111,7 +133,7 @@ dateFormat YYYY-MM-DD
 The following formatting options are supported:
 
 | Input      | Example        | Description                                            |
-| ---------- | -------------- | ------------------------------------------------------ |
+|------------|----------------|--------------------------------------------------------|
 | `YYYY`     | 2014           | 4 digit year                                           |
 | `YY`       | 14             | 2 digit year                                           |
 | `Q`        | 1..4           | Quarter of year. Sets month to first month in quarter. |
@@ -145,7 +167,7 @@ axisFormat %Y-%m-%d
 The following formatting strings are supported:
 
 | Format | Definition                                                                                |
-| ------ | ----------------------------------------------------------------------------------------- |
+|--------|-------------------------------------------------------------------------------------------|
 | %a     | abbreviated weekday name                                                                  |
 | %A     | full weekday name                                                                         |
 | %b     | abbreviated month name                                                                    |
@@ -243,7 +265,7 @@ Styling of the Gantt diagram is done by defining a number of CSS classes. During
 ### Classes used
 
 | Class                 | Description                                                            |
-| --------------------- | ---------------------------------------------------------------------- |
+|-----------------------|------------------------------------------------------------------------|
 | grid.tick             | Styling for the Grid Lines                                             |
 | grid.path             | Styling for the Grid's borders                                         |
 | .taskText             | Task Text Styling                                                      |
@@ -336,7 +358,7 @@ mermaid.ganttConfig = {
 ### Possible configuration params:
 
 | Param           | Description                                                                                                                                | Default value |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
+|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------|---------------|
 | mirrorActor     | Turns on/off the rendering of actors below the diagram as well as above it                                                                 | false         |
 | bottomMarginAdj | Adjusts how far down the graph ended. Wide borders styles with css could generate unwanted clipping which is why this config param exists. | 1             |