diff --git a/.vite/build.ts b/.vite/build.ts index 1261e375ba..019461c499 100644 --- a/.vite/build.ts +++ b/.vite/build.ts @@ -41,11 +41,6 @@ const packageOptions = { packageName: 'mermaid-mindmap', file: 'detector.ts', }, - // 'mermaid-example-diagram-detector': { - // name: 'mermaid-example-diagram-detector', - // packageName: 'mermaid-example-diagram', - // file: 'detector.ts', - // }, }; interface BuildOptions { @@ -119,11 +114,7 @@ export const getBuildConfig = ({ minify, core, watch, entryName }: BuildOptions) if (watch && config.build) { config.build.watch = { - include: [ - 'packages/mermaid-mindmap/src/**', - 'packages/mermaid/src/**', - // 'packages/mermaid-example-diagram/src/**', - ], + include: ['packages/mermaid-mindmap/src/**', 'packages/mermaid/src/**'], }; } @@ -149,7 +140,6 @@ if (watch) { build(getBuildConfig({ minify: false, watch, core: false, entryName: 'mermaid' })); if (!mermaidOnly) { build(getBuildConfig({ minify: false, watch, entryName: 'mermaid-mindmap' })); - // build(getBuildConfig({ minify: false, watch, entryName: 'mermaid-example-diagram' })); } } else if (visualize) { await build(getBuildConfig({ minify: false, core: true, entryName: 'mermaid' })); diff --git a/.vite/server.ts b/.vite/server.ts index 334398dd83..aced396ecb 100644 --- a/.vite/server.ts +++ b/.vite/server.ts @@ -1,6 +1,5 @@ import express, { NextFunction, Request, Response } from 'express'; import { createServer as createViteServer } from 'vite'; -// import { getBuildConfig } from './build'; const cors = (req: Request, res: Response, next: NextFunction) => { res.header('Access-Control-Allow-Origin', '*'); @@ -22,7 +21,7 @@ async function createServer() { app.use(cors); app.use(express.static('./packages/mermaid/dist')); - app.use(express.static('./packages/mermaid-example-diagram/dist')); + // app.use(express.static('./packages/mermaid-example-diagram/dist')); app.use(express.static('./packages/mermaid-mindmap/dist')); app.use(vite.middlewares); app.use(express.static('demos')); @@ -33,5 +32,4 @@ async function createServer() { }); } -// build(getBuildConfig({ minify: false, watch: true })); createServer(); diff --git a/cypress/integration/rendering/timeline.spec.ts b/cypress/integration/rendering/timeline.spec.ts new file mode 100644 index 0000000000..6fae82fb4e --- /dev/null +++ b/cypress/integration/rendering/timeline.spec.ts @@ -0,0 +1,164 @@ +import { imgSnapshotTest } from '../../helpers/util.js'; + +describe('Timeline diagram', () => { + it('1: should render a simple timeline with no specific sections', () => { + imgSnapshotTest( + `timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + `, + {} + ); + }); + it('2: should render a timeline diagram with sections', () => { + imgSnapshotTest( + `timeline + title Timeline of Industrial Revolution + section 17th-20th century + Industry 1.0 : Machinery, Water power, Steam
power + Industry 2.0 : Electricity, Internal combustion engine, Mass production + Industry 3.0 : Electronics, Computers, Automation + section 21st century + Industry 4.0 : Internet, Robotics, Internet of Things + Industry 5.0 : Artificial intelligence, Big data,3D printing + `, + {} + ); + }); + it('3: should render a complex timeline with sections, and long events text with
', () => { + imgSnapshotTest( + `timeline + title England's History Timeline + section Stone Age + 7600 BC : Britain's oldest known house was built in Orkney, Scotland + 6000 BC : Sea levels rise and Britain becomes an island.
The people who live here are hunter-gatherers. + section Broze Age + 2300 BC : People arrive from Europe and settle in Britain.
They bring farming and metalworking. + : New styles of pottery and ways of burying the dead appear. + 2200 BC : The last major building works are completed at Stonehenge.
People now bury their dead in stone circles. + : The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive. + `, + {} + ); + }); + it('4: should render a simple timeline with directives and disableMultiColor:true ', () => { + imgSnapshotTest( + `%%{init: { 'logLevel': 'debug', 'theme': 'base', 'timeline': {'disableMulticolor': true}}}%% + timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + `, + {} + ); + }); + it('5: should render a simple timeline with directive overriden colors', () => { + imgSnapshotTest( + ` %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': { + 'cScale0': '#ff0000', + 'cScale1': '#00ff00', + 'cScale2': '#0000ff' + } } }%% + timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + 2007 : Tumblr + 2008 : Instagram + 2010 : Pinterest + `, + {} + ); + }); + it('6: should render a simple timeline in base theme', () => { + imgSnapshotTest( + `%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%% + timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + 2007 : Tumblr + 2008 : Instagram + 2010 : Pinterest + `, + {} + ); + }); + + it('7: should render a simple timeline in default theme', () => { + imgSnapshotTest( + `%%{init: { 'logLevel': 'debug', 'theme': 'default' } }%% + timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + 2007 : Tumblr + 2008 : Instagram + 2010 : Pinterest + `, + {} + ); + }); + + it('8: should render a simple timeline in dark theme', () => { + imgSnapshotTest( + `%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%% + timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + 2007 : Tumblr + 2008 : Instagram + 2010 : Pinterest + `, + {} + ); + }); + + it('9: should render a simple timeline in neutral theme', () => { + imgSnapshotTest( + `%%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%% + timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + 2007 : Tumblr + 2008 : Instagram + 2010 : Pinterest + `, + {} + ); + }); + + it('10: should render a simple timeline in forest theme', () => { + imgSnapshotTest( + `%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%% + timeline + title History of Social Media Platform + 2002 : LinkedIn + 2004 : Facebook : Google + 2005 : Youtube + 2006 : Twitter + 2007 : Tumblr + 2008 : Instagram + 2010 : Pinterest + `, + {} + ); + }); +}); diff --git a/cypress/platform/ashish2.html b/cypress/platform/ashish2.html new file mode 100644 index 0000000000..bcea4f4cca --- /dev/null +++ b/cypress/platform/ashish2.html @@ -0,0 +1,231 @@ + + + + + + + + + + +
Security check
+ 
+ timeline
+        title My day
+        section section with no tasks
+        section Go to work at the dog office
+          1930 : first step : second step is a long step
+               : third step
+          1940 : fourth step : fifth step
+        section Go home
+          1950 : India got independent and already won war against Pakistan
+          1960 : India fights poverty, looses war to China and gets nuclear weapons from USA and USSR
+          1970 : Green Revolution comes to india
+        section Another section with no tasks
+          I am a big big big tasks
+          I am not so big tasks
+
+ 
+ timeline
+        title MermaidChart 2023 Timeline
+        section 2023 Q1 
 Release Personal Tier
+          Buttet 1 : sub-point 1a : sub-point 1b
+               : sub-point 1c
+          Bullet 2 : sub-point 2a : sub-point 2b
+        section 2023 Q2 
 Release XYZ Tier
+          Buttet 3 : sub-point 
 3a : sub-point 3b
+               : sub-point 3c
+          Bullet 4 : sub-point 4a : sub-point 4b
+
+
+ + 
+ timeline
+        title England's History Timeline
+        section Stone Age
+          7600 BC : Britain's oldest known house was built in Orkney, Scotland
+          6000 BC : Sea levels rise and Britain becomes an island. The people who live here are hunter-gatherers.
+        section Broze Age
+          2300 BC : People arrive from Europe and settle in Britain. They bring farming and metalworking.
+               : New styles of pottery and ways of burying the dead appear.
+          2200 BC : The last major building works are completed at Stonehenge. People now bury their dead in stone circles.
+                  : The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive.
+
+
+ 
+      %%{'init': { 'logLevel': 'debug', 'theme': 'default', 'timeline': {'disableMulticolor':false} } }%%
+ timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google : Pixar
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008s : Instagram
+          2010 : Pinterest
+
+ 
+      %%{init: { 'logLevel': 'debug', 'theme': 'base', 'themeVariables': {
+              'cScale0': '#ff0000',
+              'cScale1': '#00ff00',
+              'cScale2': '#ff0000'
+              } } }%%
+ timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google : Pixar
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008s : Instagram
+          2010 : Pinterest
+
+ + 
+          %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
+              'cScale0': '#ff0000',
+              'cScale1': '#00ff00',
+              'cScale2': '#0000ff'
+       } } }%%
+       timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+
+
+ + 
+ timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008s : Instagram
+          2010 : Pinterest
+
+ 
+mindmap
+  root
+    child1((Circle))
+        grandchild 1
+        grandchild 2
+    child2(Round rectangle)
+        grandchild 3
+        grandchild 4
+    child3[Square]
+        grandchild 5
+        ::icon(mdi mdi-fire)
+        gc6((grand
child 6))
+        ::icon(mdi mdi-fire)
+          gc7((grand
grand
child 8))
+
+ 
+      flowchart-elk TB
+      a --> b
+      a --> c
+      b --> d
+      c --> d
+
+ + + + + + + + diff --git a/cypress/platform/class.html b/cypress/platform/class.html index 85fae2a779..1d72c34a59 100644 --- a/cypress/platform/class.html +++ b/cypress/platform/class.html @@ -46,13 +46,9 @@

info below

       %%{init: {'theme': 'base',  'fontFamily': 'courier', 'themeVariables': {  'primaryColor': '#fff000'}}}%%
       classDiagram-v2
-       class BankAccount{
-        +String owner
-        +BigDecimal balance
-        +deposit(amount) bool
-        +withdrawl(amount) int
-       }
-       cssClass "BankAccount" customCss
+classA <|-- classB : implements
+classC *-- classD : composition
+classE o-- classF : aggregation
     
         %%{init: {'theme': 'base',  'fontFamily': 'courier', 'themeVariables': {  'primaryColor': '#fff000'}}}%%
diff --git a/cypress/platform/knsv2.html b/cypress/platform/knsv2.html
index afc12dbe93..e281846277 100644
--- a/cypress/platform/knsv2.html
+++ b/cypress/platform/knsv2.html
@@ -54,7 +54,7 @@
     
           
         
 
   
-    
+    
 %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
 graph TB
       a --> b
@@ -62,14 +62,14 @@
       b --> d
       c --> d
     

-    
+    
 flowchart-elk TB
       a --> b
       a --> c
       b --> d
       c --> d
     

-    
+    
 %%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
 flowchart TB
   %% I could not figure out how to use double quotes in labels in Mermaid
@@ -125,7 +125,7 @@
 

     

-    
+    
 flowchart TB
   %% I could not figure out how to use double quotes in labels in Mermaid
   subgraph ibm[IBM Espresso CPU]
@@ -227,14 +227,24 @@
     Customer->>+Merchant: Receives goods or services
         

-    
-      gantt
-        title Style today marker (vertical line should be 5px wide and half-transparent blue)
-        dateFormat YYYY-MM-DD
-        axisFormat %d
-        todayMarker stroke-width:5px,stroke:#00f,opacity:0.5
-        section Section1
-        Today: 1, -1h
+    
+mindmap
+  root((mindmap))
+    Origins
+      Long history
+      ::icon(fa fa-book)
+      Popularisation
+        British popular psychology author Tony Buzan
+    Research
+      On effectiveness
and features
+      On Automatic creation
+        Uses
+            Creative techniques
+            Strategic planning
+            Argument mapping
+    Tools
+      Pen and paper
+      Mermaid
     

 
     
@@ -252,7 +262,7 @@
         // console.error('Mermaid error: ', err);
       };
       mermaid.initialize({
-        // theme: 'forest',
+        theme: 'dark',
         startOnLoad: true,
         logLevel: 0,
         flowchart: {
diff --git a/demos/timeline.html b/demos/timeline.html
new file mode 100644
index 0000000000..f90f37675e
--- /dev/null
+++ b/demos/timeline.html
@@ -0,0 +1,38 @@
+
+
+  
+    
+    
+    Mermaid Quick Test Page
+    
+    
+          
         
 
+
+  
+    
+        timeline
+        title My day
+        section Go to work
+          1930 : first step : second step
+               : third step
+          1940 : fourth step : fifth step
+				

+
+    
+    
+  
+
diff --git a/docs/config/setup/modules/defaultConfig.md b/docs/config/setup/modules/defaultConfig.md
index 4089ef00d9..302bd51e14 100644
--- a/docs/config/setup/modules/defaultConfig.md
+++ b/docs/config/setup/modules/defaultConfig.md
@@ -14,7 +14,7 @@
 
 #### Defined in
 
-[defaultConfig.ts:1934](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L1934)
+[defaultConfig.ts:2084](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/defaultConfig.ts#L2084)
 
 ---
 
diff --git a/docs/config/setup/modules/mermaidAPI.md b/docs/config/setup/modules/mermaidAPI.md
index 7f9093a7bb..02d0fcf494 100644
--- a/docs/config/setup/modules/mermaidAPI.md
+++ b/docs/config/setup/modules/mermaidAPI.md
@@ -20,7 +20,7 @@ Renames and re-exports [mermaidAPI](mermaidAPI.md#mermaidapi)
 
 #### Defined in
 
-[mermaidAPI.ts:73](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L73)
+[mermaidAPI.ts:74](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L74)
 
 ## Variables
 
@@ -90,7 +90,7 @@ mermaid.initialize(config);
 
 #### Defined in
 
-[mermaidAPI.ts:962](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L962)
+[mermaidAPI.ts:886](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L886)
 
 ## Functions
 
@@ -121,7 +121,7 @@ Return the last node appended
 
 #### Defined in
 
-[mermaidAPI.ts:286](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L286)
+[mermaidAPI.ts:287](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L287)
 
 ---
 
@@ -147,7 +147,7 @@ the cleaned up svgCode
 
 #### Defined in
 
-[mermaidAPI.ts:237](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L237)
+[mermaidAPI.ts:238](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L238)
 
 ---
 
@@ -173,7 +173,7 @@ the string with all the user styles
 
 #### Defined in
 
-[mermaidAPI.ts:166](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L166)
+[mermaidAPI.ts:167](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L167)
 
 ---
 
@@ -196,7 +196,7 @@ the string with all the user styles
 
 #### Defined in
 
-[mermaidAPI.ts:214](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L214)
+[mermaidAPI.ts:215](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L215)
 
 ---
 
@@ -223,7 +223,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
 
 #### Defined in
 
-[mermaidAPI.ts:150](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L150)
+[mermaidAPI.ts:151](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L151)
 
 ---
 
@@ -243,7 +243,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
 
 #### Defined in
 
-[mermaidAPI.ts:130](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L130)
+[mermaidAPI.ts:131](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L131)
 
 ---
 
@@ -263,7 +263,7 @@ with an enclosing block that has each of the cssClasses followed by !important;
 
 #### Defined in
 
-[mermaidAPI.ts:101](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L101)
+[mermaidAPI.ts:102](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L102)
 
 ---
 
@@ -289,7 +289,7 @@ Put the svgCode into an iFrame. Return the iFrame code
 
 #### Defined in
 
-[mermaidAPI.ts:265](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L265)
+[mermaidAPI.ts:266](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L266)
 
 ---
 
@@ -314,4 +314,4 @@ Remove any existing elements from the given document
 
 #### Defined in
 
-[mermaidAPI.ts:336](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L336)
+[mermaidAPI.ts:337](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/mermaidAPI.ts#L337)
diff --git a/docs/syntax/timeline.md b/docs/syntax/timeline.md
new file mode 100644
index 0000000000..4e917bc109
--- /dev/null
+++ b/docs/syntax/timeline.md
@@ -0,0 +1,462 @@
+> **Warning**
+>
+> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
+>
+> ## Please edit the corresponding file in [/packages/mermaid/src/docs/syntax/timeline.md](../../packages/mermaid/src/docs/syntax/timeline.md).
+
+# Timeline Diagram
+
+> Timeline: This is an experimental diagram for now. The syntax and properties can change in future releases. The syntax is stable except for the icon integration which is the experimental part.
+
+"A timeline is a type of diagram used to illustrate a chronology of events, dates, or periods of time. It is usually presented graphically to indicate the passing of time, and it is usually organized chronologically. A basic timeline presents a list of events in chronological order, usually using dates as markers. A timeline can also be used to show the relationship between events, such as the relationship between the events of a person's life. A timeline can also be used to show the relationship between events, such as the relationship between the events of a person's life." Wikipedia
+
+### An example of a timeline.
+
+```mermaid-example
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook
+         : Google
+    2005 : Youtube
+    2006 : Twitter
+```
+
+```mermaid
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook
+         : Google
+    2005 : Youtube
+    2006 : Twitter
+```
+
+## Syntax
+
+The syntax for creating Timeline diagram is simple. You always start with the `timeline` keyword to let mermaid know that you want to create a timeline diagram.
+
+After that there is a possibility to add a title to the timeline. This is done by adding a line with the keyword `title` followed by the title text.
+
+Then you add the timeline data, where you always start with a time period, followed by a colon and then the text for the event. Optionally you can add a second colon and then the text for the event. So, you can have one or more events per time period.
+
+```json
+{time period} : {event}
+```
+
+or
+
+```json
+{time period} : {event} : {event}
+```
+
+or
+
+```json
+{time period} : {event}
+              : {event}
+              : {event}
+```
+
+NOTE: Both time period and event are simple text, and not limited to numbers.
+
+Let us look at the syntax for the example above.
+
+```mermaid-example
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook : Google
+    2005 : Youtube
+    2006 : Twitter
+```
+
+```mermaid
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook : Google
+    2005 : Youtube
+    2006 : Twitter
+```
+
+In this way we can use a text outline to generate a timeline diagram.
+The sequence of time period and events is important, as it will be used to draw the timeline. The first time period will be placed at the left side of the timeline, and the last time period will be placed at the right side of the timeline.
+
+Similarly, the first event will be placed at the top for that specific time period, and the last event will be placed at the bottom.
+
+## Grouping of time periods in sections/ages
+
+You can group time periods in sections/ages. This is done by adding a line with the keyword `section` followed by the section name.
+
+All subsequent time periods will be placed in this section until a new section is defined.
+
+If no section is defined, all time periods will be placed in the default section.
+
+Let us look at an example, where we have grouped the time periods in sections.
+
+```mermaid-example
+timeline
+    title Timeline of Industrial Revolution
+    section 17th-20th century
+        Industry 1.0 : Machinery, Water power, Steam 
power
+        Industry 2.0 : Electricity, Internal combustion engine, Mass production
+        Industry 3.0 : Electronics, Computers, Automation
+    section 21st century
+        Industry 4.0 : Internet, Robotics, Internet of Things
+        Industry 5.0 : Artificial intelligence, Big data,3D printing
+```
+
+```mermaid
+timeline
+    title Timeline of Industrial Revolution
+    section 17th-20th century
+        Industry 1.0 : Machinery, Water power, Steam 
power
+        Industry 2.0 : Electricity, Internal combustion engine, Mass production
+        Industry 3.0 : Electronics, Computers, Automation
+    section 21st century
+        Industry 4.0 : Internet, Robotics, Internet of Things
+        Industry 5.0 : Artificial intelligence, Big data,3D printing
+```
+
+As you can see, the time periods are placed in the sections, and the sections are placed in the order they are defined.
+
+All time periods and events under a given section follow a similar color scheme. This is done to make it easier to see the relationship between time periods and events.
+
+## Wrapping of text for long time-periods or events
+
+By default, the text for time-periods and events will be wrapped if it is too long. This is done to avoid that the text is drawn outside the diagram.
+
+You can also use `
` to force a line break.
+
+Let us look at another example, where we have a long time period, and a long event.
+
+```mermaid-example
+timeline
+        title England's History Timeline
+        section Stone Age
+          7600 BC : Britain's oldest known house was built in Orkney, Scotland
+          6000 BC : Sea levels rise and Britain becomes an island.
 The people who live here are hunter-gatherers.
+        section Broze Age
+          2300 BC : People arrive from Europe and settle in Britain. 
They bring farming and metalworking.
+                  : New styles of pottery and ways of burying the dead appear.
+          2200 BC : The last major building works are completed at Stonehenge.
 People now bury their dead in stone circles.
+                  : The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive.
+
+```
+
+```mermaid
+timeline
+        title England's History Timeline
+        section Stone Age
+          7600 BC : Britain's oldest known house was built in Orkney, Scotland
+          6000 BC : Sea levels rise and Britain becomes an island.
 The people who live here are hunter-gatherers.
+        section Broze Age
+          2300 BC : People arrive from Europe and settle in Britain. 
They bring farming and metalworking.
+                  : New styles of pottery and ways of burying the dead appear.
+          2200 BC : The last major building works are completed at Stonehenge.
 People now bury their dead in stone circles.
+                  : The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive.
+
+```
+
+```mermaid-example
+timeline
+        title MermaidChart 2023 Timeline
+        section 2023 Q1 
 Release Personal Tier
+          Buttet 1 : sub-point 1a : sub-point 1b
+               : sub-point 1c
+          Bullet 2 : sub-point 2a : sub-point 2b
+        section 2023 Q2 
 Release XYZ Tier
+          Buttet 3 : sub-point 
 3a : sub-point 3b
+               : sub-point 3c
+          Bullet 4 : sub-point 4a : sub-point 4b
+```
+
+```mermaid
+timeline
+        title MermaidChart 2023 Timeline
+        section 2023 Q1 
 Release Personal Tier
+          Buttet 1 : sub-point 1a : sub-point 1b
+               : sub-point 1c
+          Bullet 2 : sub-point 2a : sub-point 2b
+        section 2023 Q2 
 Release XYZ Tier
+          Buttet 3 : sub-point 
 3a : sub-point 3b
+               : sub-point 3c
+          Bullet 4 : sub-point 4a : sub-point 4b
+```
+
+## Styling of time periods and events
+
+As explained earlier, each section has a color scheme, and each time period and event under a section follow the similar color scheme.
+
+However, if there is no section defined, then we have two possibilities:
+
+1.  Style time periods individually, i.e. each time period(and its coressponding events) will have its own color scheme. This is the DEFAULT behavior.
+
+```mermaid-example
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+
+```
+
+```mermaid
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+
+```
+
+Note that this is no, section defined, and each time period and its corresponding events will have its own color scheme.
+
+2.  Disable the multiColor option using the `disableMultiColor` option. This will make all time periods and events follow the same color scheme.
+
+You will need to add this option either via mermaid.intialize function or directives.
+
+```javascript
+mermaid.initialize({
+        theme: 'base',
+        startOnLoad: true,
+        logLevel: 0,
+        timeline: {
+          disableMulticolor: false,
+        },
+        ...
+        ...
+```
+
+let us look at same example, where we have disabled the multiColor option.
+
+```mermaid-example
+   %%{init: { 'logLevel': 'debug', 'theme': 'base', 'timeline': {'disableMulticolor': true}}}%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+
+```
+
+```mermaid
+   %%{init: { 'logLevel': 'debug', 'theme': 'base', 'timeline': {'disableMulticolor': true}}}%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+
+```
+
+### Customizing Color scheme
+
+You can customize the color scheme using the `cScale0` to `cScale11` theme variables. Mermaid allows you to set unique colors for up-to 12, where `cScale0` variable will drive the value of the first section or time-period, `cScale1` will drive the value of the second section and so on.
+In case you have more than 12 sections, the color scheme will start to repeat.
+
+NOTE: Default values for these theme variables are picked from the selected theme. If you want to override the default values, you can use the `initialize` call to add your custom theme variable values.
+
+Example:
+
+Now let's override the default values for the `cScale0` to `cScale2` variables:
+
+```mermaid-example
+    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
+              'cScale0': '#ff0000',
+              'cScale1': '#00ff00',
+              'cScale2': '#0000ff'
+       } } }%%
+       timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+
+```
+
+```mermaid
+    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
+              'cScale0': '#ff0000',
+              'cScale1': '#00ff00',
+              'cScale2': '#0000ff'
+       } } }%%
+       timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+
+```
+
+See how the colors are changed to the values specified in the theme variables.
+
+## Themes
+
+Mermaid supports a bunch of pre-defined themes which you can use to find the right one for you. PS: you can actually override an existing theme's variable to get your own custom theme going. Learn more about theming your diagram [here](../config/theming.md).
+
+The following are the different pre-defined theme options:
+
+- `base`
+- `forest`
+- `dark`
+- `default`
+- `neutral`
+
+**NOTE**: To change theme you can either use the `initialize` call or _directives_. Learn more about [directives](../config/directives.md)
+Let's put them to use, and see how our sample diagram looks in different themes:
+
+### Base Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Forest Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Dark Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Default Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'default' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'default' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Neutral Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+```mermaid
+%%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+You can also refer the implementation in the live editor [here](https://github.com/mermaid-js/mermaid-live-editor/blob/fcf53c98c25604c90a218104268c339be53035a6/src/lib/util/mermaid.ts) to see how the async loading is done.
diff --git a/packages/mermaid-example-diagram/src/mermaidUtils.ts b/packages/mermaid-example-diagram/src/mermaidUtils.ts
index 8894abdff5..9ba66be5a8 100644
--- a/packages/mermaid-example-diagram/src/mermaidUtils.ts
+++ b/packages/mermaid-example-diagram/src/mermaidUtils.ts
@@ -22,6 +22,7 @@ export const log: Record = {
 export let setLogLevel: (level: keyof typeof LEVELS | number | string) => void;
 export let getConfig: () => object;
 export let sanitizeText: (str: string) => string;
+export let commonDb: any;
 /**
  * Placeholder for the real function that will be injected by mermaid.
  */
@@ -41,15 +42,17 @@ export let setupGraphViewbox: (
  * @param _getConfig - getConfig from mermaid/src/diagramAPI.ts
  * @param _sanitizeText - sanitizeText from mermaid/src/diagramAPI.ts
  * @param _setupGraphViewbox - setupGraphViewbox from mermaid/src/diagramAPI.ts
+ * @param _commonDb -`commonDb` from mermaid/src/diagramAPI.ts
  */
 export const injectUtils = (
   _log: Record,
   _setLogLevel: typeof setLogLevel,
   _getConfig: typeof getConfig,
   _sanitizeText: typeof sanitizeText,
-  _setupGraphViewbox: typeof setupGraphViewbox
+  _setupGraphViewbox: typeof setupGraphViewbox,
+  _commonDb: any
 ) => {
-  _log.debug('Mermaid utils injected into example-diagram');
+  _log.info('Mermaid utils injected into timeline-diagram');
   log.trace = _log.trace;
   log.debug = _log.debug;
   log.info = _log.info;
@@ -60,4 +63,5 @@ export const injectUtils = (
   getConfig = _getConfig;
   sanitizeText = _sanitizeText;
   setupGraphViewbox = _setupGraphViewbox;
+  commonDb = _commonDb;
 };
diff --git a/packages/mermaid-mindmap/src/mermaidUtils.ts b/packages/mermaid-mindmap/src/mermaidUtils.ts
index b575c201b1..44cc85f73c 100644
--- a/packages/mermaid-mindmap/src/mermaidUtils.ts
+++ b/packages/mermaid-mindmap/src/mermaidUtils.ts
@@ -27,6 +27,7 @@ export const log: Record = {
 export let setLogLevel: (level: keyof typeof LEVELS | number | string) => void;
 export let getConfig: () => object;
 export let sanitizeText: (str: string) => string;
+export let commonDb: () => object;
 // eslint-disable @typescript-eslint/no-explicit-any
 export let setupGraphViewbox: (
   graph: any,
@@ -40,7 +41,8 @@ export const injectUtils = (
   _setLogLevel: any,
   _getConfig: any,
   _sanitizeText: any,
-  _setupGraphViewbox: any
+  _setupGraphViewbox: any,
+  _commonDb: any
 ) => {
   _log.info('Mermaid utils injected');
   log.trace = _log.trace;
@@ -53,4 +55,5 @@ export const injectUtils = (
   getConfig = _getConfig;
   sanitizeText = _sanitizeText;
   setupGraphViewbox = _setupGraphViewbox;
+  commonDb = _commonDb;
 };
diff --git a/packages/mermaid-mindmap/src/mindmap.spec.js b/packages/mermaid-mindmap/src/mindmap.spec.js
index e3f018350b..753804a5de 100644
--- a/packages/mermaid-mindmap/src/mindmap.spec.js
+++ b/packages/mermaid-mindmap/src/mindmap.spec.js
@@ -347,4 +347,40 @@ root
     expect(child.children.length).toEqual(2);
     expect(child.children[1].nodeId).toEqual('b');
   });
+  it('MMP-23 Rows with only spaces should not interfere', function () {
+    let str = 'mindmap\nroot\n A\n \n\n B';
+    mindmap.parse(str);
+    const mm = mindmap.yy.getMindmap();
+    expect(mm.nodeId).toEqual('root');
+    expect(mm.children.length).toEqual(2);
+
+    const child = mm.children[0];
+    expect(child.nodeId).toEqual('A');
+    const child2 = mm.children[1];
+    expect(child2.nodeId).toEqual('B');
+  });
+  it('MMP-24 Handle rows above the mindmap declarations', function () {
+    let str = '\n \nmindmap\nroot\n A\n \n\n B';
+    mindmap.parse(str);
+    const mm = mindmap.yy.getMindmap();
+    expect(mm.nodeId).toEqual('root');
+    expect(mm.children.length).toEqual(2);
+
+    const child = mm.children[0];
+    expect(child.nodeId).toEqual('A');
+    const child2 = mm.children[1];
+    expect(child2.nodeId).toEqual('B');
+  });
+  it('MMP-25 Handle rows above the mindmap declarations, no space', function () {
+    let str = '\n\n\nmindmap\nroot\n A\n \n\n B';
+    mindmap.parse(str);
+    const mm = mindmap.yy.getMindmap();
+    expect(mm.nodeId).toEqual('root');
+    expect(mm.children.length).toEqual(2);
+
+    const child = mm.children[0];
+    expect(child.nodeId).toEqual('A');
+    const child2 = mm.children[1];
+    expect(child2.nodeId).toEqual('B');
+  });
 });
diff --git a/packages/mermaid-mindmap/src/mindmapRenderer.js b/packages/mermaid-mindmap/src/mindmapRenderer.js
index 9fd557e516..6ffe80f5e8 100644
--- a/packages/mermaid-mindmap/src/mindmapRenderer.js
+++ b/packages/mermaid-mindmap/src/mindmapRenderer.js
@@ -89,6 +89,7 @@ function addNodes(mindmap, cy, conf, level) {
 /**
  * @param node
  * @param conf
+ * @param cy
  */
 function layoutMindmap(node, conf) {
   return new Promise((resolve) => {
@@ -131,7 +132,10 @@ function layoutMindmap(node, conf) {
   });
 }
 /**
+ * @param node
  * @param cy
+ * @param positionedMindmap
+ * @param conf
  */
 function positionNodes(cy) {
   cy.nodes().map((node, id) => {
diff --git a/packages/mermaid-mindmap/src/parser/mindmap.jison b/packages/mermaid-mindmap/src/parser/mindmap.jison
index a96ee62614..d2f6bbf1af 100644
--- a/packages/mermaid-mindmap/src/parser/mindmap.jison
+++ b/packages/mermaid-mindmap/src/parser/mindmap.jison
@@ -25,6 +25,7 @@
 \n				   { this.popState();}
 // [\s]*"::icon("   { this.begin('ICON'); }
 "::icon("   { yy.getLogger().trace('Begin icon');this.begin('ICON'); }
+[\s]+[\n]     {yy.getLogger().trace('SPACELINE');return 'SPACELINE'                 /* skip all whitespace */    ;}
 [\n]+               return 'NL';
 [^\)]+			 { return 'ICON'; }
 \)				   {yy.getLogger().trace('end icon');this.popState();}
@@ -64,14 +65,25 @@
 
 start
 // %{	: info document 'EOF' { return yy; } }
-	: MINDMAP document  { return yy; }
-	| MINDMAP NL document  { return yy; }
-  |	SPACELIST MINDMAP document  { return yy; }
-	;
+	: mindMap
+  |	spaceLines mindMap
+  ;
+
+spaceLines
+  : SPACELINE
+  | spaceLines SPACELINE
+  | spaceLines NL
+  ;
+
+mindMap
+  : MINDMAP document  { return yy; }
+  | MINDMAP NL document  { return yy; }
+  ;
 
 stop
   : NL {yy.getLogger().trace('Stop NL ');}
   | EOF {yy.getLogger().trace('Stop EOF ');}
+  | SPACELINE
   | stop NL {yy.getLogger().trace('Stop NL2 ');}
   | stop EOF {yy.getLogger().trace('Stop EOF2 ');}
   ;
@@ -81,9 +93,10 @@ document
 	;
 
 statement
-	: SPACELIST node       { yy.getLogger().trace('Node: ',$2.id);yy.addNode($1.length, $2.id, $2.descr, $2.type);  }
+	: SPACELIST node       { yy.getLogger().info('Node: ',$2.id);yy.addNode($1.length, $2.id, $2.descr, $2.type);  }
 	| SPACELIST ICON       { yy.getLogger().trace('Icon: ',$2);yy.decorateNode({icon: $2}); }
 	| SPACELIST CLASS      { yy.decorateNode({class: $2}); }
+  | SPACELINE { yy.getLogger().trace('SPACELIST');}
 	| node					       { yy.getLogger().trace('Node: ',$1.id);yy.addNode(0, $1.id, $1.descr, $1.type);  }
 	| ICON                 { yy.decorateNode({icon: $1}); }
 	| CLASS                { yy.decorateNode({class: $1}); }
diff --git a/packages/mermaid-mindmap/src/svgDraw.js b/packages/mermaid-mindmap/src/svgDraw.js
index d4f57f1f17..2b1aa021e2 100644
--- a/packages/mermaid-mindmap/src/svgDraw.js
+++ b/packages/mermaid-mindmap/src/svgDraw.js
@@ -203,15 +203,14 @@ const roundedRectBkg = function (elem, node) {
  * @returns {number} The height nodes dom element
  */
 export const drawNode = function (elem, node, fullSection, conf) {
-  const section = (fullSection % MAX_SECTIONS) - 1;
+  const section = fullSection % (MAX_SECTIONS - 1);
   const nodeElem = elem.append('g');
   node.section = section;
-  nodeElem.attr(
-    'class',
-    (node.class ? node.class + ' ' : '') +
-      'mindmap-node ' +
-      (section < 0 ? 'section-root' : 'section-' + section)
-  );
+  let sectionClass = 'section-' + section;
+  if (section < 0) {
+    sectionClass += ' section-root';
+  }
+  nodeElem.attr('class', (node.class ? node.class + ' ' : '') + 'mindmap-node ' + sectionClass);
   const bkgElem = nodeElem.append('g');
 
   // Create the wrapped text element
@@ -305,7 +304,7 @@ export const drawNode = function (elem, node, fullSection, conf) {
 };
 
 export const drawEdge = function drawEdge(edgesElem, mindmap, parent, depth, fullSection) {
-  const section = (fullSection % MAX_SECTIONS) - 1;
+  const section = fullSection % (MAX_SECTIONS - 1);
   const sx = parent.x + parent.width / 2;
   const sy = parent.y + parent.height / 2;
   const ex = mindmap.x + mindmap.width / 2;
diff --git a/packages/mermaid/src/Diagram.ts b/packages/mermaid/src/Diagram.ts
index ed0762ece5..1f68e52ba7 100644
--- a/packages/mermaid/src/Diagram.ts
+++ b/packages/mermaid/src/Diagram.ts
@@ -44,7 +44,7 @@ export class Diagram {
     this.parser.parser.yy = this.db;
     if (diagram.init) {
       diagram.init(cnf);
-      log.debug('Initialized diagram ' + this.type, cnf);
+      log.info('Initialized diagram ' + this.type, cnf);
     }
     this.txt += '\n';
 
diff --git a/packages/mermaid/src/config.type.ts b/packages/mermaid/src/config.type.ts
index ff199ca8b1..4740758242 100644
--- a/packages/mermaid/src/config.type.ts
+++ b/packages/mermaid/src/config.type.ts
@@ -26,6 +26,7 @@ export interface MermaidConfig {
   sequence?: SequenceDiagramConfig;
   gantt?: GanttDiagramConfig;
   journey?: JourneyDiagramConfig;
+  timeline?: TimelineDiagramConfig;
   class?: ClassDiagramConfig;
   state?: StateDiagramConfig;
   er?: ErDiagramConfig;
@@ -292,6 +293,30 @@ export interface JourneyDiagramConfig extends BaseDiagramConfig {
   sectionColours?: string[];
 }
 
+export interface TimelineDiagramConfig extends BaseDiagramConfig {
+  diagramMarginX?: number;
+  diagramMarginY?: number;
+  leftMargin?: number;
+  width?: number;
+  height?: number;
+  boxMargin?: number;
+  boxTextMargin?: number;
+  noteMargin?: number;
+  messageMargin?: number;
+  messageAlign?: string;
+  bottomMarginAdj?: number;
+  rightAngles?: boolean;
+  taskFontSize?: string | number;
+  taskFontFamily?: string;
+  taskMargin?: number;
+  activationWidth?: number;
+  textPlacement?: string;
+  actorColours?: string[];
+  sectionFills?: string[];
+  sectionColours?: string[];
+  disableMulticolor?: boolean;
+}
+
 export interface GanttDiagramConfig extends BaseDiagramConfig {
   titleTopMargin?: number;
   barHeight?: number;
diff --git a/packages/mermaid/src/defaultConfig.ts b/packages/mermaid/src/defaultConfig.ts
index fb6d88d99e..ec741e9080 100644
--- a/packages/mermaid/src/defaultConfig.ts
+++ b/packages/mermaid/src/defaultConfig.ts
@@ -862,6 +862,156 @@ const config: Partial = {
     sectionFills: ['#191970', '#8B008B', '#4B0082', '#2F4F4F', '#800000', '#8B4513', '#00008B'],
     sectionColours: ['#fff'],
   },
+  /** The object containing configurations specific for timeline diagrams */
+  timeline: {
+    /**
+     * | Parameter      | Description                                          | Type    | Required | Values             |
+     * | -------------- | ---------------------------------------------------- | ------- | -------- | ------------------ |
+     * | diagramMarginX | Margin to the right and left of the sequence diagram | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 50
+     */
+    diagramMarginX: 50,
+
+    /**
+     * | Parameter      | Description                                        | Type    | Required | Values             |
+     * | -------------- | -------------------------------------------------- | ------- | -------- | ------------------ |
+     * | diagramMarginY | Margin to the over and under the sequence diagram. | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 10
+     */
+    diagramMarginY: 10,
+
+    /**
+     * | Parameter   | Description           | Type    | Required | Values             |
+     * | ----------- | --------------------- | ------- | -------- | ------------------ |
+     * | actorMargin | Margin between actors | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 50
+     */
+    leftMargin: 150,
+
+    /**
+     * | Parameter | Description          | Type    | Required | Values             |
+     * | --------- | -------------------- | ------- | -------- | ------------------ |
+     * | width     | Width of actor boxes | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 150
+     */
+    width: 150,
+
+    /**
+     * | Parameter | Description           | Type    | Required | Values             |
+     * | --------- | --------------------- | ------- | -------- | ------------------ |
+     * | height    | Height of actor boxes | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 65
+     */
+    height: 50,
+
+    /**
+     * | Parameter | Description              | Type    | Required | Values             |
+     * | --------- | ------------------------ | ------- | -------- | ------------------ |
+     * | boxMargin | Margin around loop boxes | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 10
+     */
+    boxMargin: 10,
+
+    /**
+     * | Parameter     | Description                                  | Type    | Required | Values             |
+     * | ------------- | -------------------------------------------- | ------- | -------- | ------------------ |
+     * | boxTextMargin | Margin around the text in loop/alt/opt boxes | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 5
+     */
+    boxTextMargin: 5,
+
+    /**
+     * | Parameter  | Description         | Type    | Required | Values             |
+     * | ---------- | ------------------- | ------- | -------- | ------------------ |
+     * | noteMargin | Margin around notes | Integer | Required | Any Positive Value |
+     *
+     * **Notes:** Default value: 10
+     */
+    noteMargin: 10,
+
+    /**
+     * | Parameter     | Description             | Type    | Required | Values             |
+     * | ------------- | ----------------------- | ------- | -------- | ------------------ |
+     * | messageMargin | Space between messages. | Integer | Required | Any Positive Value |
+     *
+     * **Notes:**
+     *
+     * Space between messages.
+     *
+     * Default value: 35
+     */
+    messageMargin: 35,
+
+    /**
+     * | Parameter    | Description                 | Type | Required | Values                    |
+     * | ------------ | --------------------------- | ---- | -------- | ------------------------- |
+     * | messageAlign | Multiline message alignment | 3    | 4        | 'left', 'center', 'right' |
+     *
+     * **Notes:** Default value: 'center'
+     */
+    messageAlign: 'center',
+
+    /**
+     * | Parameter       | Description                                | Type    | Required | Values             |
+     * | --------------- | ------------------------------------------ | ------- | -------- | ------------------ |
+     * | bottomMarginAdj | Prolongs the edge of the diagram downwards | Integer | 4        | Any Positive Value |
+     *
+     * **Notes:**
+     *
+     * Depending on css styling this might need adjustment.
+     *
+     * Default value: 1
+     */
+    bottomMarginAdj: 1,
+
+    /**
+     * | Parameter   | Description | Type    | Required | Values      |
+     * | ----------- | ----------- | ------- | -------- | ----------- |
+     * | useMaxWidth | See notes   | boolean | 4        | true, false |
+     *
+     * **Notes:**
+     *
+     * 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,
+
+    /**
+     * | Parameter   | Description                       | Type | Required | Values      |
+     * | ----------- | --------------------------------- | ---- | -------- | ----------- |
+     * | rightAngles | Curved Arrows become Right Angles | 3    | 4        | true, false |
+     *
+     * **Notes:**
+     *
+     * This will display arrows that start and begin at the same node as right angles, rather than a
+     * curves
+     *
+     * Default value: false
+     */
+    rightAngles: false,
+    taskFontSize: 14,
+    taskFontFamily: '"Open Sans", sans-serif',
+    taskMargin: 50,
+    // width of activation box
+    activationWidth: 10,
+
+    // text placement as: tspan | fo | old only text as before
+    textPlacement: 'fo',
+    actorColours: ['#8FBC8F', '#7CFC00', '#00FFFF', '#20B2AA', '#B0E0E6', '#FFFFE0'],
+
+    sectionFills: ['#191970', '#8B008B', '#4B0082', '#2F4F4F', '#800000', '#8B4513', '#00008B'],
+    sectionColours: ['#fff'],
+    disableMulticolor: false,
+  },
   class: {
     /**
      * ### titleTopMargin
diff --git a/packages/mermaid/src/diagram-api/diagram-orchestration.ts b/packages/mermaid/src/diagram-api/diagram-orchestration.ts
index ce54f6f18f..81ddb6163d 100644
--- a/packages/mermaid/src/diagram-api/diagram-orchestration.ts
+++ b/packages/mermaid/src/diagram-api/diagram-orchestration.ts
@@ -1,5 +1,4 @@
 import { registerDiagram } from './diagramAPI';
-
 // @ts-ignore: TODO Fix ts errors
 import gitGraphParser from '../diagrams/git/parser/gitGraph';
 import { gitGraphDetector } from '../diagrams/git/gitGraphDetector';
@@ -97,6 +96,7 @@ import errorStyles from '../diagrams/error/styles';
 import flowchartElk from '../diagrams/flowchart/elk/detector';
 import { registerLazyLoadedDiagrams } from './detectType';
 
+import timelineDetector from '../diagrams/timeline/detector';
 let hasLoadedDiagrams = false;
 export const addDiagrams = () => {
   if (hasLoadedDiagrams) {
@@ -105,7 +105,7 @@ export const addDiagrams = () => {
   // This is added here to avoid race-conditions.
   // We could optimize the loading logic somehow.
   hasLoadedDiagrams = true;
-  registerLazyLoadedDiagrams(flowchartElk);
+  registerLazyLoadedDiagrams(flowchartElk, timelineDetector);
 
   registerDiagram(
     'error',
diff --git a/packages/mermaid/src/diagram-api/diagramAPI.ts b/packages/mermaid/src/diagram-api/diagramAPI.ts
index 748cc5f962..936e43efdb 100644
--- a/packages/mermaid/src/diagram-api/diagramAPI.ts
+++ b/packages/mermaid/src/diagram-api/diagramAPI.ts
@@ -5,6 +5,8 @@ import { sanitizeText as _sanitizeText } from '../diagrams/common/common';
 import { setupGraphViewbox as _setupGraphViewbox } from '../setupGraphViewbox';
 import { addStylesForDiagram } from '../styles';
 import { DiagramDefinition, DiagramDetector } from './types';
+import * as _commonDb from '../commonDb';
+import { parseDirective as _parseDirective } from '../directiveUtils';
 
 /*
   Packaging and exposing resources for external diagrams so that they can import
@@ -16,6 +18,11 @@ export const setLogLevel = _setLogLevel;
 export const getConfig = _getConfig;
 export const sanitizeText = (text: string) => _sanitizeText(text, getConfig());
 export const setupGraphViewbox = _setupGraphViewbox;
+export const getCommonDb = () => {
+  return _commonDb;
+};
+export const parseDirective = (p: any, statement: string, context: string, type: string) =>
+  _parseDirective(p, statement, context, type);
 
 const diagrams: Record = {};
 export interface Detectors {
@@ -46,7 +53,15 @@ export const registerDiagram = (
   addStylesForDiagram(id, diagram.styles);
 
   if (diagram.injectUtils) {
-    diagram.injectUtils(log, setLogLevel, getConfig, sanitizeText, setupGraphViewbox);
+    diagram.injectUtils(
+      log,
+      setLogLevel,
+      getConfig,
+      sanitizeText,
+      setupGraphViewbox,
+      getCommonDb(),
+      parseDirective
+    );
   }
 };
 
diff --git a/packages/mermaid/src/diagram-api/types.ts b/packages/mermaid/src/diagram-api/types.ts
index 3449782e20..d600195770 100644
--- a/packages/mermaid/src/diagram-api/types.ts
+++ b/packages/mermaid/src/diagram-api/types.ts
@@ -6,6 +6,8 @@ export interface InjectUtils {
   _getConfig: any;
   _sanitizeText: any;
   _setupGraphViewbox: any;
+  _commonDb: any;
+  _parseDirective: any;
 }
 
 /**
@@ -29,7 +31,9 @@ export interface DiagramDefinition {
     _setLogLevel: InjectUtils['_setLogLevel'],
     _getConfig: InjectUtils['_getConfig'],
     _sanitizeText: InjectUtils['_sanitizeText'],
-    _setupGraphViewbox: InjectUtils['_setupGraphViewbox']
+    _setupGraphViewbox: InjectUtils['_setupGraphViewbox'],
+    _commonDb: InjectUtils['_commonDb'],
+    _parseDirective: InjectUtils['_parseDirective']
   ) => void;
 }
 
diff --git a/packages/mermaid/src/diagrams/timeline/detector.ts b/packages/mermaid/src/diagrams/timeline/detector.ts
new file mode 100644
index 0000000000..9d06d6438a
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/detector.ts
@@ -0,0 +1,20 @@
+import type { ExternalDiagramDefinition } from '../../diagram-api/types';
+
+const id = 'timeline';
+
+const detector = (txt: string) => {
+  return txt.match(/^\s*timeline/) !== null;
+};
+
+const loader = async () => {
+  const { diagram } = await import('./diagram-definition');
+  return { id, diagram };
+};
+
+const plugin: ExternalDiagramDefinition = {
+  id,
+  detector,
+  loader,
+};
+
+export default plugin;
diff --git a/packages/mermaid/src/diagrams/timeline/diagram-definition.ts b/packages/mermaid/src/diagrams/timeline/diagram-definition.ts
new file mode 100644
index 0000000000..898af8b785
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/diagram-definition.ts
@@ -0,0 +1,12 @@
+// @ts-ignore: TODO Fix ts errors
+import parser from './parser/timeline.jison';
+import * as db from './timelineDb';
+import renderer from './timelineRenderer';
+import styles from './styles';
+
+export const diagram = {
+  db,
+  renderer,
+  parser,
+  styles,
+};
diff --git a/packages/mermaid/src/diagrams/timeline/parser/timeline.jison b/packages/mermaid/src/diagrams/timeline/parser/timeline.jison
new file mode 100644
index 0000000000..59b96516a4
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/parser/timeline.jison
@@ -0,0 +1,112 @@
+/** mermaid
+ *  https://mermaidjs.github.io/
+ *  (c) 2023 Knut Sveidqvist
+ *  MIT license.
+ */
+%lex
+%options case-insensitive
+%x acc_title
+%x acc_descr
+%x acc_descr_multiline
+
+// Directive states
+%x open_directive type_directive arg_directive
+
+
+%%
+
+\%\%\{                                                          { this.begin('open_directive'); return 'open_directive'; }
+((?:(?!\}\%\%)[^:.])*)                          { this.begin('type_directive'); return 'type_directive'; }
+":"                                             { this.popState(); this.begin('arg_directive'); return ':'; }
+\}\%\%                            { this.popState(); this.popState(); return 'close_directive'; }
+((?:(?!\}\%\%).|\n)*)                            return 'arg_directive';
+\%%(?!\{)[^\n]*                                                 /* skip comments */
+[^\}]\%\%[^\n]*                                                 /* skip comments */
+[\n]+                   return 'NEWLINE';
+\s+                     /* skip whitespace */
+\#[^\n]*                /* skip comments */
+
+"timeline"               return 'timeline';
+"title"\s[^#\n;]+       return 'title';
+accTitle\s*":"\s*                                               { this.begin("acc_title");return 'acc_title'; }
+(?!\n|;|#)*[^\n]*                                    { this.popState(); return "acc_title_value"; }
+accDescr\s*":"\s*                                               { this.begin("acc_descr");return 'acc_descr'; }
+(?!\n|;|#)*[^\n]*                                    { this.popState(); return "acc_descr_value"; }
+accDescr\s*"{"\s*                                { this.begin("acc_descr_multiline");}
+[\}]                       { this.popState(); }
+[^\}]*                     return "acc_descr_multiline_value";
+"section"\s[^#:\n;]+    return 'section';
+
+// event starting with "==>" keyword
+":"\s[^#:\n;]+        return 'event';
+[^#:\n;]+               return 'period';
+
+
+<>                 return 'EOF';
+.                       return 'INVALID';
+
+/lex
+
+%left '^'
+
+%start start
+
+%% /* language grammar */
+
+start
+	: timeline document 'EOF' { return $2; }
+	| directive start
+	;
+
+document
+	: /* empty */ { $$ = [] }
+	| document line {$1.push($2);$$ = $1}
+	;
+
+line
+	: SPACE statement { $$ = $2 }
+	| statement { $$ = $1 }
+	| NEWLINE { $$=[];}
+	| EOF { $$=[];}
+	;
+
+directive
+  : openDirective typeDirective closeDirective 'NEWLINE'
+  | openDirective typeDirective ':' argDirective closeDirective 'NEWLINE'
+  ;
+
+statement
+  : title {yy.getCommonDb().setDiagramTitle($1.substr(6));$$=$1.substr(6);}
+  | acc_title acc_title_value  { $$=$2.trim();yy.getCommonDb().setAccTitle($$); }
+  | acc_descr acc_descr_value  { $$=$2.trim();yy.getCommonDb().setAccDescription($$); }
+  | acc_descr_multiline_value { $$=$1.trim();yy.getCommonDb().setAccDescription($$); }
+  | section {yy.addSection($1.substr(8));$$=$1.substr(8);}
+  | period_statement
+  | event_statement
+  | directive
+  ;
+period_statement
+  : period {yy.addTask($1,0,'');$$=$1;}
+;
+event_statement
+  : event {yy.addEvent($1.substr(2));$$=$1;}
+;
+
+
+openDirective
+  : open_directive { yy.parseDirective('%%{', 'open_directive'); }
+  ;
+
+typeDirective
+  : type_directive { yy.parseDirective($1, 'type_directive'); }
+  ;
+
+argDirective
+  : arg_directive { $1 = $1.trim().replace(/'/g, '"'); yy.parseDirective($1, 'arg_directive'); }
+  ;
+
+closeDirective
+  : close_directive { yy.parseDirective('}%%', 'close_directive', 'timeline'); }
+  ;
+
+%%
diff --git a/packages/mermaid/src/diagrams/timeline/styles.js b/packages/mermaid/src/diagrams/timeline/styles.js
new file mode 100644
index 0000000000..fd9526e987
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/styles.js
@@ -0,0 +1,81 @@
+import { darken, lighten, isDark } from 'khroma';
+
+const genSections = (options) => {
+  let sections = '';
+
+  for (let i = 0; i < options.THEME_COLOR_LIMIT; i++) {
+    options['lineColor' + i] = options['lineColor' + i] || options['cScaleInv' + i];
+    if (isDark(options['lineColor' + i])) {
+      options['lineColor' + i] = lighten(options['lineColor' + i], 20);
+    } else {
+      options['lineColor' + i] = darken(options['lineColor' + i], 20);
+    }
+  }
+
+  for (let i = 0; i < options.THEME_COLOR_LIMIT; i++) {
+    const sw = '' + (17 - 3 * i);
+    sections += `
+    .section-${i - 1} rect, .section-${i - 1} path, .section-${i - 1} circle, .section-${
+      i - 1
+    } path  {
+      fill: ${options['cScale' + i]};
+    }
+    .section-${i - 1} text {
+     fill: ${options['cScaleLabel' + i]};
+    }
+    .node-icon-${i - 1} {
+      font-size: 40px;
+      color: ${options['cScaleLabel' + i]};
+    }
+    .section-edge-${i - 1}{
+      stroke: ${options['cScale' + i]};
+    }
+    .edge-depth-${i - 1}{
+      stroke-width: ${sw};
+    }
+    .section-${i - 1} line {
+      stroke: ${options['cScaleInv' + i]} ;
+      stroke-width: 3;
+    }
+
+    .lineWrapper line{
+      stroke: ${options['cScaleLabel' + i]} ;
+    }
+
+    .disabled, .disabled circle, .disabled text {
+      fill: lightgray;
+    }
+    .disabled text {
+      fill: #efefef;
+    }
+    `;
+  }
+  return sections;
+};
+
+const getStyles = (options) =>
+  `
+  .edge {
+    stroke-width: 3;
+  }
+  ${genSections(options)}
+  .section-root rect, .section-root path, .section-root circle  {
+    fill: ${options.git0};
+  }
+  .section-root text {
+    fill: ${options.gitBranchLabel0};
+  }
+  .icon-container {
+    height:100%;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+  }
+  .edge {
+    fill: none;
+  }
+  .eventWrapper  {
+   filter: brightness(120%);
+  }
+`;
+export default getStyles;
diff --git a/packages/mermaid/src/diagrams/timeline/svgDraw.js b/packages/mermaid/src/diagrams/timeline/svgDraw.js
new file mode 100644
index 0000000000..874ac62ef0
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/svgDraw.js
@@ -0,0 +1,602 @@
+import { arc as d3arc, select } from 'd3';
+const MAX_SECTIONS = 12;
+
+export const drawRect = function (elem, rectData) {
+  const rectElem = elem.append('rect');
+  rectElem.attr('x', rectData.x);
+  rectElem.attr('y', rectData.y);
+  rectElem.attr('fill', rectData.fill);
+  rectElem.attr('stroke', rectData.stroke);
+  rectElem.attr('width', rectData.width);
+  rectElem.attr('height', rectData.height);
+  rectElem.attr('rx', rectData.rx);
+  rectElem.attr('ry', rectData.ry);
+
+  if (rectData.class !== undefined) {
+    rectElem.attr('class', rectData.class);
+  }
+
+  return rectElem;
+};
+
+export const drawFace = function (element, faceData) {
+  const radius = 15;
+  const circleElement = element
+    .append('circle')
+    .attr('cx', faceData.cx)
+    .attr('cy', faceData.cy)
+    .attr('class', 'face')
+    .attr('r', radius)
+    .attr('stroke-width', 2)
+    .attr('overflow', 'visible');
+
+  const face = element.append('g');
+
+  //left eye
+  face
+    .append('circle')
+    .attr('cx', faceData.cx - radius / 3)
+    .attr('cy', faceData.cy - radius / 3)
+    .attr('r', 1.5)
+    .attr('stroke-width', 2)
+    .attr('fill', '#666')
+    .attr('stroke', '#666');
+
+  //right eye
+  face
+    .append('circle')
+    .attr('cx', faceData.cx + radius / 3)
+    .attr('cy', faceData.cy - radius / 3)
+    .attr('r', 1.5)
+    .attr('stroke-width', 2)
+    .attr('fill', '#666')
+    .attr('stroke', '#666');
+
+  /** @param {any} face */
+  function smile(face) {
+    const arc = d3arc()
+      .startAngle(Math.PI / 2)
+      .endAngle(3 * (Math.PI / 2))
+      .innerRadius(radius / 2)
+      .outerRadius(radius / 2.2);
+    //mouth
+    face
+      .append('path')
+      .attr('class', 'mouth')
+      .attr('d', arc)
+      .attr('transform', 'translate(' + faceData.cx + ',' + (faceData.cy + 2) + ')');
+  }
+
+  /** @param {any} face */
+  function sad(face) {
+    const arc = d3arc()
+      .startAngle((3 * Math.PI) / 2)
+      .endAngle(5 * (Math.PI / 2))
+      .innerRadius(radius / 2)
+      .outerRadius(radius / 2.2);
+    //mouth
+    face
+      .append('path')
+      .attr('class', 'mouth')
+      .attr('d', arc)
+      .attr('transform', 'translate(' + faceData.cx + ',' + (faceData.cy + 7) + ')');
+  }
+
+  /** @param {any} face */
+  function ambivalent(face) {
+    face
+      .append('line')
+      .attr('class', 'mouth')
+      .attr('stroke', 2)
+      .attr('x1', faceData.cx - 5)
+      .attr('y1', faceData.cy + 7)
+      .attr('x2', faceData.cx + 5)
+      .attr('y2', faceData.cy + 7)
+      .attr('class', 'mouth')
+      .attr('stroke-width', '1px')
+      .attr('stroke', '#666');
+  }
+
+  if (faceData.score > 3) {
+    smile(face);
+  } else if (faceData.score < 3) {
+    sad(face);
+  } else {
+    ambivalent(face);
+  }
+
+  return circleElement;
+};
+
+export const drawCircle = function (element, circleData) {
+  const circleElement = element.append('circle');
+  circleElement.attr('cx', circleData.cx);
+  circleElement.attr('cy', circleData.cy);
+  circleElement.attr('class', 'actor-' + circleData.pos);
+  circleElement.attr('fill', circleData.fill);
+  circleElement.attr('stroke', circleData.stroke);
+  circleElement.attr('r', circleData.r);
+
+  if (circleElement.class !== undefined) {
+    circleElement.attr('class', circleElement.class);
+  }
+
+  if (circleData.title !== undefined) {
+    circleElement.append('title').text(circleData.title);
+  }
+
+  return circleElement;
+};
+
+export const drawText = function (elem, textData) {
+  // Remove and ignore br:s
+  const nText = textData.text.replace(//gi, ' ');
+
+  const textElem = elem.append('text');
+  textElem.attr('x', textData.x);
+  textElem.attr('y', textData.y);
+  textElem.attr('class', 'legend');
+
+  textElem.style('text-anchor', textData.anchor);
+
+  if (textData.class !== undefined) {
+    textElem.attr('class', textData.class);
+  }
+
+  const span = textElem.append('tspan');
+  span.attr('x', textData.x + textData.textMargin * 2);
+  span.text(nText);
+
+  return textElem;
+};
+
+export const drawLabel = function (elem, txtObject) {
+  /**
+   * @param {any} x
+   * @param {any} y
+   * @param {any} width
+   * @param {any} height
+   * @param {any} cut
+   */
+  function genPoints(x, y, width, height, cut) {
+    return (
+      x +
+      ',' +
+      y +
+      ' ' +
+      (x + width) +
+      ',' +
+      y +
+      ' ' +
+      (x + width) +
+      ',' +
+      (y + height - cut) +
+      ' ' +
+      (x + width - cut * 1.2) +
+      ',' +
+      (y + height) +
+      ' ' +
+      x +
+      ',' +
+      (y + height)
+    );
+  }
+  const polygon = elem.append('polygon');
+  polygon.attr('points', genPoints(txtObject.x, txtObject.y, 50, 20, 7));
+  polygon.attr('class', 'labelBox');
+
+  txtObject.y = txtObject.y + txtObject.labelMargin;
+  txtObject.x = txtObject.x + 0.5 * txtObject.labelMargin;
+  drawText(elem, txtObject);
+};
+
+export const drawSection = function (elem, section, conf) {
+  const g = elem.append('g');
+
+  const rect = getNoteRect();
+  rect.x = section.x;
+  rect.y = section.y;
+  rect.fill = section.fill;
+  rect.width = conf.width;
+  rect.height = conf.height;
+  rect.class = 'journey-section section-type-' + section.num;
+  rect.rx = 3;
+  rect.ry = 3;
+  drawRect(g, rect);
+
+  _drawTextCandidateFunc(conf)(
+    section.text,
+    g,
+    rect.x,
+    rect.y,
+    rect.width,
+    rect.height,
+    { class: 'journey-section section-type-' + section.num },
+    conf,
+    section.colour
+  );
+};
+
+let taskCount = -1;
+/**
+ * Draws an actor in the diagram with the attached line
+ *
+ * @param {any} elem The HTML element
+ * @param {any} task The task to render
+ * @param {any} conf The global configuration
+ */
+export const drawTask = function (elem, task, conf) {
+  const center = task.x + conf.width / 2;
+  const g = elem.append('g');
+  taskCount++;
+  const maxHeight = 300 + 5 * 30;
+  g.append('line')
+    .attr('id', 'task' + taskCount)
+    .attr('x1', center)
+    .attr('y1', task.y)
+    .attr('x2', center)
+    .attr('y2', maxHeight)
+    .attr('class', 'task-line')
+    .attr('stroke-width', '1px')
+    .attr('stroke-dasharray', '4 2')
+    .attr('stroke', '#666');
+
+  drawFace(g, {
+    cx: center,
+    cy: 300 + (5 - task.score) * 30,
+    score: task.score,
+  });
+
+  const rect = getNoteRect();
+  rect.x = task.x;
+  rect.y = task.y;
+  rect.fill = task.fill;
+  rect.width = conf.width;
+  rect.height = conf.height;
+  rect.class = 'task task-type-' + task.num;
+  rect.rx = 3;
+  rect.ry = 3;
+  drawRect(g, rect);
+
+  let xPos = task.x + 14;
+  // task.people.forEach((person) => {
+  //   const colour = task.actors[person].color;
+
+  //   const circle = {
+  //     cx: xPos,
+  //     cy: task.y,
+  //     r: 7,
+  //     fill: colour,
+  //     stroke: '#000',
+  //     title: person,
+  //     pos: task.actors[person].position,
+  //   };
+
+  //   drawCircle(g, circle);
+  //   xPos += 10;
+  // });
+
+  _drawTextCandidateFunc(conf)(
+    task.task,
+    g,
+    rect.x,
+    rect.y,
+    rect.width,
+    rect.height,
+    { class: 'task' },
+    conf,
+    task.colour
+  );
+};
+
+/**
+ * Draws a background rectangle
+ *
+ * @param {any} elem The html element
+ * @param {any} bounds The bounds of the drawing
+ */
+export const drawBackgroundRect = function (elem, bounds) {
+  const rectElem = drawRect(elem, {
+    x: bounds.startx,
+    y: bounds.starty,
+    width: bounds.stopx - bounds.startx,
+    height: bounds.stopy - bounds.starty,
+    fill: bounds.fill,
+    class: 'rect',
+  });
+  rectElem.lower();
+};
+
+export const getTextObj = function () {
+  return {
+    x: 0,
+    y: 0,
+    fill: undefined,
+    'text-anchor': 'start',
+    width: 100,
+    height: 100,
+    textMargin: 0,
+    rx: 0,
+    ry: 0,
+  };
+};
+
+export const getNoteRect = function () {
+  return {
+    x: 0,
+    y: 0,
+    width: 100,
+    anchor: 'start',
+    height: 100,
+    rx: 0,
+    ry: 0,
+  };
+};
+
+const _drawTextCandidateFunc = (function () {
+  /**
+   * @param {any} content
+   * @param {any} g
+   * @param {any} x
+   * @param {any} y
+   * @param {any} width
+   * @param {any} height
+   * @param {any} textAttrs
+   * @param {any} colour
+   */
+  function byText(content, g, x, y, width, height, textAttrs, colour) {
+    const text = g
+      .append('text')
+      .attr('x', x + width / 2)
+      .attr('y', y + height / 2 + 5)
+      .style('font-color', colour)
+      .style('text-anchor', 'middle')
+      .text(content);
+    _setTextAttrs(text, textAttrs);
+  }
+
+  /**
+   * @param {any} content
+   * @param {any} g
+   * @param {any} x
+   * @param {any} y
+   * @param {any} width
+   * @param {any} height
+   * @param {any} textAttrs
+   * @param {any} conf
+   * @param {any} colour
+   */
+  function byTspan(content, g, x, y, width, height, textAttrs, conf, colour) {
+    const { taskFontSize, taskFontFamily } = conf;
+
+    const lines = content.split(//gi);
+    for (let i = 0; i < lines.length; i++) {
+      const dy = i * taskFontSize - (taskFontSize * (lines.length - 1)) / 2;
+      const text = g
+        .append('text')
+        .attr('x', x + width / 2)
+        .attr('y', y)
+        .attr('fill', colour)
+        .style('text-anchor', 'middle')
+        .style('font-size', taskFontSize)
+        .style('font-family', taskFontFamily);
+      text
+        .append('tspan')
+        .attr('x', x + width / 2)
+        .attr('dy', dy)
+        .text(lines[i]);
+
+      text
+        .attr('y', y + height / 2.0)
+        .attr('dominant-baseline', 'central')
+        .attr('alignment-baseline', 'central');
+
+      _setTextAttrs(text, textAttrs);
+    }
+  }
+
+  /**
+   * @param {any} content
+   * @param {any} g
+   * @param {any} x
+   * @param {any} y
+   * @param {any} width
+   * @param {any} height
+   * @param {any} textAttrs
+   * @param {any} conf
+   */
+  function byFo(content, g, x, y, width, height, textAttrs, conf) {
+    const body = g.append('switch');
+    const f = body
+      .append('foreignObject')
+      .attr('x', x)
+      .attr('y', y)
+      .attr('width', width)
+      .attr('height', height)
+      .attr('position', 'fixed');
+
+    const text = f
+      .append('xhtml:div')
+      .style('display', 'table')
+      .style('height', '100%')
+      .style('width', '100%');
+
+    text
+      .append('div')
+      .attr('class', 'label')
+      .style('display', 'table-cell')
+      .style('text-align', 'center')
+      .style('vertical-align', 'middle')
+      .text(content);
+
+    byTspan(content, body, x, y, width, height, textAttrs, conf);
+    _setTextAttrs(text, textAttrs);
+  }
+
+  /**
+   * @param {any} toText
+   * @param {any} fromTextAttrsDict
+   */
+  function _setTextAttrs(toText, fromTextAttrsDict) {
+    for (const key in fromTextAttrsDict) {
+      if (key in fromTextAttrsDict) {
+        // noinspection JSUnfilteredForInLoop
+        toText.attr(key, fromTextAttrsDict[key]);
+      }
+    }
+  }
+
+  return function (conf) {
+    return conf.textPlacement === 'fo' ? byFo : conf.textPlacement === 'old' ? byText : byTspan;
+  };
+})();
+
+const initGraphics = function (graphics) {
+  graphics
+    .append('defs')
+    .append('marker')
+    .attr('id', 'arrowhead')
+    .attr('refX', 5)
+    .attr('refY', 2)
+    .attr('markerWidth', 6)
+    .attr('markerHeight', 4)
+    .attr('orient', 'auto')
+    .append('path')
+    .attr('d', 'M 0,0 V 4 L6,2 Z'); // this is actual shape for arrowhead
+};
+
+/**
+ * @param {string} text The text to be wrapped
+ * @param {number} width The max width of the text
+ */
+function wrap(text, width) {
+  text.each(function () {
+    var text = select(this),
+      words = text
+        .text()
+        .split(/(\s+|
)/)
+        .reverse(),
+      word,
+      line = [],
+      lineHeight = 1.1, // ems
+      y = text.attr('y'),
+      dy = parseFloat(text.attr('dy')),
+      tspan = text
+        .text(null)
+        .append('tspan')
+        .attr('x', 0)
+        .attr('y', y)
+        .attr('dy', dy + 'em');
+    for (let j = 0; j < words.length; j++) {
+      word = words[words.length - 1 - j];
+      line.push(word);
+      tspan.text(line.join(' ').trim());
+      if (tspan.node().getComputedTextLength() > width || word === '
') {
+        line.pop();
+        tspan.text(line.join(' ').trim());
+        if (word === '
') {
+          line = [''];
+        } else {
+          line = [word];
+        }
+
+        tspan = text
+          .append('tspan')
+          .attr('x', 0)
+          .attr('y', y)
+          .attr('dy', lineHeight + 'em')
+          .text(word);
+      }
+    }
+  });
+}
+
+export const drawNode = function (elem, node, fullSection, conf) {
+  const section = (fullSection % MAX_SECTIONS) - 1;
+  const nodeElem = elem.append('g');
+  node.section = section;
+  nodeElem.attr(
+    'class',
+    (node.class ? node.class + ' ' : '') + 'timeline-node ' + ('section-' + section)
+  );
+  const bkgElem = nodeElem.append('g');
+
+  // Create the wrapped text element
+  const textElem = nodeElem.append('g');
+
+  const txt = textElem
+    .append('text')
+    .text(node.descr)
+    .attr('dy', '1em')
+    .attr('alignment-baseline', 'middle')
+    .attr('dominant-baseline', 'middle')
+    .attr('text-anchor', 'middle')
+    .call(wrap, node.width);
+  const bbox = txt.node().getBBox();
+  const fontSize =
+    conf.fontSize && conf.fontSize.replace ? conf.fontSize.replace('px', '') : conf.fontSize;
+  node.height = bbox.height + fontSize * 1.1 * 0.5 + node.padding;
+  node.height = Math.max(node.height, node.maxHeight);
+  node.width = node.width + 2 * node.padding;
+
+  textElem.attr('transform', 'translate(' + node.width / 2 + ', ' + node.padding / 2 + ')');
+
+  // Create the background element
+  defaultBkg(bkgElem, node, section, conf);
+
+  return node;
+};
+
+export const getVirtualNodeHeight = function (elem, node, conf) {
+  const textElem = elem.append('g');
+  const txt = textElem
+    .append('text')
+    .text(node.descr)
+    .attr('dy', '1em')
+    .attr('alignment-baseline', 'middle')
+    .attr('dominant-baseline', 'middle')
+    .attr('text-anchor', 'middle')
+    .call(wrap, node.width);
+  const bbox = txt.node().getBBox();
+  const fontSize =
+    conf.fontSize && conf.fontSize.replace ? conf.fontSize.replace('px', '') : conf.fontSize;
+  textElem.remove();
+  return bbox.height + fontSize * 1.1 * 0.5 + node.padding;
+};
+
+const defaultBkg = function (elem, node, section) {
+  const rd = 5;
+  elem
+    .append('path')
+    .attr('id', 'node-' + node.id)
+    .attr('class', 'node-bkg node-' + node.type)
+    .attr(
+      'd',
+      `M0 ${node.height - rd} v${-node.height + 2 * rd} q0,-5 5,-5 h${
+        node.width - 2 * rd
+      } q5,0 5,5 v${node.height - rd} H0 Z`
+    );
+
+  elem
+    .append('line')
+    .attr('class', 'node-line-' + section)
+    .attr('x1', 0)
+    .attr('y1', node.height)
+    .attr('x2', node.width)
+    .attr('y2', node.height);
+};
+
+export default {
+  drawRect,
+  drawCircle,
+  drawSection,
+  drawText,
+  drawLabel,
+  drawTask,
+  drawBackgroundRect,
+  getTextObj,
+  getNoteRect,
+  initGraphics,
+  drawNode,
+  getVirtualNodeHeight,
+};
diff --git a/packages/mermaid/src/diagrams/timeline/timeline.spec.js b/packages/mermaid/src/diagrams/timeline/timeline.spec.js
new file mode 100644
index 0000000000..0697b194e2
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/timeline.spec.js
@@ -0,0 +1,122 @@
+import { parser as timeline } from './parser/timeline';
+import * as timelineDB from './timelineDb';
+// import { injectUtils } from './mermaidUtils';
+import * as _commonDb from '../../commonDb';
+import { parseDirective as _parseDirective } from '../../directiveUtils';
+
+import {
+  log,
+  setLogLevel,
+  getConfig,
+  sanitizeText,
+  setupGraphViewBox,
+} from '../../diagram-api/diagramAPI';
+
+// injectUtils(
+//   log,
+//   setLogLevel,
+//   getConfig,
+//   sanitizeText,
+//   setupGraphViewBox,
+//   _commonDb,
+//   _parseDirective
+// );
+
+describe('when parsing a timeline ', function () {
+  beforeEach(function () {
+    timeline.yy = timelineDB;
+    timelineDB.clear();
+    setLogLevel('trace');
+  });
+  describe('Timeline', function () {
+    it('TL-1 should handle a simple section definition abc-123', function () {
+      let str = `timeline
+    section abc-123`;
+
+      timeline.parse(str);
+      expect(timelineDB.getSections()).to.deep.equal(['abc-123']);
+    });
+
+    it('TL-2 should handle a simple section and only two tasks', function () {
+      let str = `timeline
+    section abc-123
+    task1
+    task2`;
+      timeline.parse(str);
+      timelineDB.getTasks().forEach((task) => {
+        expect(task.section).to.equal('abc-123');
+        expect(task.task).to.be.oneOf(['task1', 'task2']);
+      });
+    });
+
+    it('TL-3 should handle a two section and two coressponding tasks', function () {
+      let str = `timeline
+    section abc-123
+    task1
+    task2
+    section abc-456
+    task3
+    task4`;
+      timeline.parse(str);
+      expect(timelineDB.getSections()).to.deep.equal(['abc-123', 'abc-456']);
+      timelineDB.getTasks().forEach((task) => {
+        expect(task.section).to.be.oneOf(['abc-123', 'abc-456']);
+        expect(task.task).to.be.oneOf(['task1', 'task2', 'task3', 'task4']);
+        if (task.section === 'abc-123') {
+          expect(task.task).to.be.oneOf(['task1', 'task2']);
+        } else {
+          expect(task.task).to.be.oneOf(['task3', 'task4']);
+        }
+      });
+    });
+
+    it('TL-4 should handle a section, and task and its events', function () {
+      let str = `timeline
+    section abc-123
+      task1: event1
+      task2: event2: event3
+   `;
+      timeline.parse(str);
+      expect(timelineDB.getSections()[0]).to.deep.equal('abc-123');
+      timelineDB.getTasks().forEach((t) => {
+        switch (t.task.trim()) {
+          case 'task1':
+            expect(t.events).to.deep.equal(['event1']);
+            break;
+
+          case 'task2':
+            expect(t.events).to.deep.equal(['event2', 'event3']);
+            break;
+
+          default:
+            break;
+        }
+      });
+    });
+
+    it('TL-5 should handle a section, and task and its multi line events', function () {
+      let str = `timeline
+    section abc-123
+      task1: event1
+      task2: event2: event3
+           : event4: event5
+   `;
+      timeline.parse(str);
+      expect(timelineDB.getSections()[0]).to.deep.equal('abc-123');
+      timelineDB.getTasks().forEach((t) => {
+        switch (t.task.trim()) {
+          case 'task1':
+            expect(t.events).to.deep.equal(['event1']);
+            break;
+
+          case 'task2':
+            expect(t.events).to.deep.equal(['event2', 'event3', 'event4', 'event5']);
+            break;
+
+          default:
+            break;
+        }
+      });
+    });
+  });
+});
diff --git a/packages/mermaid/src/diagrams/timeline/timelineDb.js b/packages/mermaid/src/diagrams/timeline/timelineDb.js
new file mode 100644
index 0000000000..7bc5c26923
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/timelineDb.js
@@ -0,0 +1,108 @@
+import { parseDirective as _parseDirective } from '../../directiveUtils';
+import * as commonDb from '../../commonDb';
+let currentSection = '';
+let currentTaskId = 0;
+
+const sections = [];
+const tasks = [];
+const rawTasks = [];
+
+export const getCommonDb = () => commonDb;
+
+export const parseDirective = (statement, context, type) => {
+  _parseDirective(this, statement, context, type);
+};
+
+export const clear = function () {
+  sections.length = 0;
+  tasks.length = 0;
+  currentSection = '';
+  rawTasks.length = 0;
+  commonDb.clear();
+};
+
+export const addSection = function (txt) {
+  currentSection = txt;
+  sections.push(txt);
+};
+
+export const getSections = function () {
+  return sections;
+};
+
+export const getTasks = function () {
+  let allItemsProcessed = compileTasks();
+  const maxDepth = 100;
+  let iterationCount = 0;
+  while (!allItemsProcessed && iterationCount < maxDepth) {
+    allItemsProcessed = compileTasks();
+    iterationCount++;
+  }
+
+  tasks.push(...rawTasks);
+
+  return tasks;
+};
+
+export const addTask = function (period, length, event) {
+  const rawTask = {
+    id: currentTaskId++,
+    section: currentSection,
+    type: currentSection,
+    task: period,
+    score: length ? length : 0,
+    //if event is defined, then add it the events array
+    events: event ? [event] : [],
+  };
+  rawTasks.push(rawTask);
+};
+
+export const addEvent = function (event) {
+  // fetch current task with currnetTaskId
+  const currentTask = rawTasks.find((task) => task.id === currentTaskId - 1);
+  //add event to the events array
+  currentTask.events.push(event);
+};
+
+export const addTaskOrg = function (descr) {
+  const newTask = {
+    section: currentSection,
+    type: currentSection,
+    description: descr,
+    task: descr,
+    classes: [],
+  };
+  tasks.push(newTask);
+};
+
+/**
+ * Compiles the raw tasks into a list of tasks with events
+ * @returns {boolean} true if all items are processed
+ * @private
+ * @memberof timelineDb
+ */
+const compileTasks = function () {
+  const compileTask = function (pos) {
+    return rawTasks[pos].processed;
+  };
+
+  let allProcessed = true;
+  for (const [i, rawTask] of rawTasks.entries()) {
+    compileTask(i);
+
+    allProcessed = allProcessed && rawTask.processed;
+  }
+  return allProcessed;
+};
+
+export default {
+  clear,
+  getCommonDb,
+  addSection,
+  getSections,
+  getTasks,
+  addTask,
+  addTaskOrg,
+  addEvent,
+  parseDirective,
+};
diff --git a/packages/mermaid/src/diagrams/timeline/timelineRenderer.ts b/packages/mermaid/src/diagrams/timeline/timelineRenderer.ts
new file mode 100644
index 0000000000..02e706bf6c
--- /dev/null
+++ b/packages/mermaid/src/diagrams/timeline/timelineRenderer.ts
@@ -0,0 +1,336 @@
+// @ts-nocheck TODO: fix file
+import { select } from 'd3';
+import svgDraw from './svgDraw';
+import { log } from '../../logger';
+import { getConfig } from '../../config';
+import { setupGraphViewbox } from '../../setupGraphViewbox';
+
+export const setConf = function (cnf) {
+  const keys = Object.keys(cnf);
+
+  keys.forEach(function (key) {
+    conf[key] = cnf[key];
+  });
+};
+
+export const draw = function (text, id, version, diagObj) {
+  //1. Fetch the configuration
+  const conf = getConfig();
+  const LEFT_MARGIN = conf.leftMargin ? conf.leftMargin : 50;
+
+  //2. Clear the diagram db before parsing
+  diagObj.db.clear();
+
+  //3. Parse the diagram text
+  diagObj.parser.parse(text + '\n');
+
+  log.debug('timeline', diagObj.db);
+
+  const securityLevel = conf.securityLevel;
+  // Handle root and Document for when rendering in sandbox mode
+  let sandboxElement;
+  if (securityLevel === 'sandbox') {
+    sandboxElement = select('#i' + id);
+  }
+  const root =
+    securityLevel === 'sandbox'
+      ? select(sandboxElement.nodes()[0].contentDocument.body)
+      : select('body');
+
+  const svg = root.select('#' + id);
+
+  svg.append('g');
+
+  //4. Fetch the diagram data
+  const tasks = diagObj.db.getTasks();
+  const title = diagObj.db.getCommonDb().getDiagramTitle();
+  log.debug('task', tasks);
+
+  //5. Initialize the diagram
+  svgDraw.initGraphics(svg);
+
+  // fetch Sections
+  const sections = diagObj.db.getSections();
+  log.debug('sections', sections);
+
+  let maxSectionHeight = 0;
+  let maxTaskHeight = 0;
+  //let sectionBeginX = 0;
+  let depthY = 0;
+  let sectionBeginY = 0;
+  let masterX = 50 + LEFT_MARGIN;
+  //sectionBeginX = masterX;
+  let masterY = 50;
+  sectionBeginY = 50;
+  //draw sections
+  let sectionNumber = 0;
+  let hasSections = true;
+
+  //Calculate the max height of the sections
+  sections.forEach(function (section) {
+    const sectionNode = {
+      number: sectionNumber,
+      descr: section,
+      section: sectionNumber,
+      width: 150,
+      padding: 20,
+      maxHeight: maxSectionHeight,
+    };
+    const sectionHeight = svgDraw.getVirtualNodeHeight(svg, sectionNode, conf);
+    log.debug('sectionHeight before draw', sectionHeight);
+    maxSectionHeight = Math.max(maxSectionHeight, sectionHeight + 20);
+  });
+
+  //tasks length and maxEventCount
+  let maxEventCount = 0;
+  let maxEventLineLength = 0;
+  log.debug('tasks.length', tasks.length);
+  //calculate max task height
+  // for loop till tasks.length
+  for (const [i, task] of tasks.entries()) {
+    const taskNode = {
+      number: i,
+      descr: task,
+      section: task.section,
+      width: 150,
+      padding: 20,
+      maxHeight: maxTaskHeight,
+    };
+    const taskHeight = svgDraw.getVirtualNodeHeight(svg, taskNode, conf);
+    log.debug('taskHeight before draw', taskHeight);
+    maxTaskHeight = Math.max(maxTaskHeight, taskHeight + 20);
+
+    //calculate maxEventCount
+    maxEventCount = Math.max(maxEventCount, task.events.length);
+    //calculate maxEventLineLength
+    let maxEventLineLengthTemp = 0;
+    for (let j = 0; j < task.events.length; j++) {
+      const event = task.events[j];
+      const eventNode = {
+        descr: event,
+        section: task.section,
+        number: task.section,
+        width: 150,
+        padding: 20,
+        maxHeight: 50,
+      };
+      maxEventLineLengthTemp += svgDraw.getVirtualNodeHeight(svg, eventNode, conf);
+    }
+    maxEventLineLength = Math.max(maxEventLineLength, maxEventLineLengthTemp);
+  }
+
+  log.debug('maxSectionHeight before draw', maxSectionHeight);
+  log.debug('maxTaskHeight before draw', maxTaskHeight);
+
+  if (sections && sections.length > 0) {
+    sections.forEach((section) => {
+      const sectionNode = {
+        number: sectionNumber,
+        descr: section,
+        section: sectionNumber,
+        width: 150,
+        padding: 20,
+        maxHeight: maxSectionHeight,
+      };
+      log.debug('sectionNode', sectionNode);
+      const sectionNodeWrapper = svg.append('g');
+      const node = svgDraw.drawNode(sectionNodeWrapper, sectionNode, sectionNumber, conf);
+      log.debug('sectionNode output', node);
+
+      sectionNodeWrapper.attr('transform', `translate(${masterX}, ${sectionBeginY})`);
+
+      masterY += maxSectionHeight + 50;
+
+      //draw tasks for this section
+      //filter task where tasks.section == section
+      const tasksForSection = tasks.filter((task) => task.section === section);
+      if (tasksForSection.length > 0) {
+        drawTasks(
+          svg,
+          tasksForSection,
+          sectionNumber,
+          masterX,
+          masterY,
+          maxTaskHeight,
+          conf,
+          maxEventCount,
+          maxEventLineLength,
+          maxSectionHeight,
+          false
+        );
+      }
+      // todo replace with total width of section and its tasks
+      masterX += 200 * Math.max(tasksForSection.length, 1);
+
+      masterY = sectionBeginY;
+      sectionNumber++;
+    });
+  } else {
+    //draw tasks
+    hasSections = false;
+    drawTasks(
+      svg,
+      tasks,
+      sectionNumber,
+      masterX,
+      masterY,
+      maxTaskHeight,
+      conf,
+      maxEventCount,
+      maxEventLineLength,
+      maxSectionHeight,
+      true
+    );
+  }
+
+  // Get BBox of the diagram
+  const box = svg.node().getBBox();
+  log.debug('bounds', box);
+
+  if (title) {
+    svg
+      .append('text')
+      .text(title)
+      .attr('x', box.width / 2 - LEFT_MARGIN)
+      .attr('font-size', '4ex')
+      .attr('font-weight', 'bold')
+      .attr('y', 20);
+  }
+  //5. Draw the diagram
+  depthY = hasSections ? maxSectionHeight + maxTaskHeight + 150 : maxTaskHeight + 100;
+
+  const lineWrapper = svg.append('g').attr('class', 'lineWrapper');
+  // Draw activity line
+  lineWrapper
+    .append('line')
+    .attr('x1', LEFT_MARGIN)
+    .attr('y1', depthY) // One section head + one task + margins
+    .attr('x2', box.width + 3 * LEFT_MARGIN) // Subtract stroke width so arrow point is retained
+    .attr('y2', depthY)
+    .attr('stroke-width', 4)
+    .attr('stroke', 'black')
+    .attr('marker-end', 'url(#arrowhead)');
+
+  // Setup the view box and size of the svg element
+  setupGraphViewbox(
+    undefined,
+    svg,
+    conf.timeline.padding ? conf.timeline.padding : 50,
+    conf.timeline.useMaxWidth ? conf.timeline.useMaxWidth : false
+  );
+
+  // addSVGAccessibilityFields(diagObj.db, diagram, id);
+};
+
+export const drawTasks = function (
+  diagram,
+  tasks,
+  sectionColor,
+  masterX,
+  masterY,
+  maxTaskHeight,
+  conf,
+  maxEventCount,
+  maxEventLineLength,
+  maxSectionHeight,
+  isWithoutSections
+) {
+  // Draw the tasks
+  for (const task of tasks) {
+    // create node from task
+    const taskNode = {
+      descr: task.task,
+      section: sectionColor,
+      number: sectionColor,
+      width: 150,
+      padding: 20,
+      maxHeight: maxTaskHeight,
+    };
+
+    log.debug('taskNode', taskNode);
+    // create task wrapper
+    const taskWrapper = diagram.append('g').attr('class', 'taskWrapper');
+    const node = svgDraw.drawNode(taskWrapper, taskNode, sectionColor, conf);
+    const taskHeight = node.height;
+    //log task height
+    log.debug('taskHeight after draw', taskHeight);
+    taskWrapper.attr('transform', `translate(${masterX}, ${masterY})`);
+
+    // update max task height
+    maxTaskHeight = Math.max(maxTaskHeight, taskHeight);
+
+    // if task has events, draw them
+    if (task.events) {
+      // draw a line between the task and the events
+      const lineWrapper = diagram.append('g').attr('class', 'lineWrapper');
+      let linelength = maxTaskHeight;
+      //add margin to task
+      masterY += 100;
+      linelength =
+        linelength + drawEvents(diagram, task.events, sectionColor, masterX, masterY, conf);
+      masterY -= 100;
+
+      lineWrapper
+        .append('line')
+        .attr('x1', masterX + 190 / 2)
+        .attr('y1', masterY + maxTaskHeight) // One section head + one task + margins
+        .attr('x2', masterX + 190 / 2) // Subtract stroke width so arrow point is retained
+        .attr(
+          'y2',
+          masterY +
+            maxTaskHeight +
+            (isWithoutSections ? maxTaskHeight : maxSectionHeight) +
+            maxEventLineLength +
+            120
+        )
+        .attr('stroke-width', 2)
+        .attr('stroke', 'black')
+        .attr('marker-end', 'url(#arrowhead)')
+        .attr('stroke-dasharray', '5,5');
+    }
+
+    masterX = masterX + 200;
+    if (isWithoutSections && !getConfig().timeline.disableMulticolor) {
+      sectionColor++;
+    }
+  }
+
+  // reset Y coordinate for next section
+  masterY = masterY - 10;
+};
+
+export const drawEvents = function (diagram, events, sectionColor, masterX, masterY, conf) {
+  let maxEventHeight = 0;
+  const eventBeginY = masterY;
+  masterY = masterY + 100;
+  // Draw the events
+  for (const event of events) {
+    // create node from event
+    const eventNode = {
+      descr: event,
+      section: sectionColor,
+      number: sectionColor,
+      width: 150,
+      padding: 20,
+      maxHeight: 50,
+    };
+
+    //log task node
+    log.debug('eventNode', eventNode);
+    // create event wrapper
+    const eventWrapper = diagram.append('g').attr('class', 'eventWrapper');
+    const node = svgDraw.drawNode(eventWrapper, eventNode, sectionColor, conf);
+    const eventHeight = node.height;
+    maxEventHeight = maxEventHeight + eventHeight;
+    eventWrapper.attr('transform', `translate(${masterX}, ${masterY})`);
+    masterY = masterY + 10 + eventHeight;
+  }
+  // set masterY back to eventBeginY
+  masterY = eventBeginY;
+  return maxEventHeight;
+};
+
+export default {
+  setConf,
+  draw,
+};
diff --git a/packages/mermaid/src/directiveUtils.ts b/packages/mermaid/src/directiveUtils.ts
new file mode 100644
index 0000000000..2d2971a857
--- /dev/null
+++ b/packages/mermaid/src/directiveUtils.ts
@@ -0,0 +1,87 @@
+import * as configApi from './config';
+
+import { log } from './logger';
+import { directiveSanitizer } from './utils';
+
+let currentDirective: { type?: string; args?: any } | undefined = {};
+
+export const parseDirective = function (
+  p: any,
+  statement: string,
+  context: string,
+  type: string
+): void {
+  log.debug('parseDirective is being called', statement, context, type);
+  try {
+    if (statement !== undefined) {
+      statement = statement.trim();
+      switch (context) {
+        case 'open_directive':
+          currentDirective = {};
+          break;
+        case 'type_directive':
+          if (!currentDirective) {
+            throw new Error('currentDirective is undefined');
+          }
+          currentDirective.type = statement.toLowerCase();
+          break;
+        case 'arg_directive':
+          if (!currentDirective) {
+            throw new Error('currentDirective is undefined');
+          }
+          currentDirective.args = JSON.parse(statement);
+          break;
+        case 'close_directive':
+          handleDirective(p, currentDirective, type);
+          currentDirective = undefined;
+          break;
+      }
+    }
+  } catch (error) {
+    log.error(
+      `Error while rendering sequenceDiagram directive: ${statement} jison context: ${context}`
+    );
+    // @ts-ignore: TODO Fix ts errors
+    log.error(error.message);
+  }
+};
+
+const handleDirective = function (p: any, directive: any, type: string): void {
+  log.info(`Directive type=${directive.type} with args:`, directive.args);
+  switch (directive.type) {
+    case 'init':
+    case 'initialize': {
+      ['config'].forEach((prop) => {
+        if (directive.args[prop] !== undefined) {
+          if (type === 'flowchart-v2') {
+            type = 'flowchart';
+          }
+          directive.args[type] = directive.args[prop];
+          delete directive.args[prop];
+        }
+      });
+      log.info('sanitize in handleDirective', directive.args);
+      directiveSanitizer(directive.args);
+      log.info('sanitize in handleDirective (done)', directive.args);
+      configApi.addDirective(directive.args);
+      break;
+    }
+    case 'wrap':
+    case 'nowrap':
+      if (p && p['setWrap']) {
+        p.setWrap(directive.type === 'wrap');
+      }
+      break;
+    case 'themeCss':
+      log.warn('themeCss encountered');
+      break;
+    default:
+      log.warn(
+        `Unhandled directive: source: '%%{${directive.type}: ${JSON.stringify(
+          directive.args ? directive.args : {}
+        )}}%%`,
+        directive
+      );
+      break;
+  }
+};
diff --git a/packages/mermaid/src/docs/.vitepress/config.ts b/packages/mermaid/src/docs/.vitepress/config.ts
index a6d1579bbf..396029a96a 100644
--- a/packages/mermaid/src/docs/.vitepress/config.ts
+++ b/packages/mermaid/src/docs/.vitepress/config.ts
@@ -104,6 +104,7 @@ function sidebarSyntax() {
         { text: 'Gitgraph (Git) Diagram 🔥', link: '/syntax/gitgraph' },
         { text: 'C4C Diagram (Context) Diagram 🦺⚠️', link: '/syntax/c4c' },
         { text: 'Mindmaps 🔥', link: '/syntax/mindmap' },
+        { text: 'Timeline 🔥', link: '/syntax/timeline' },
         { text: 'Other Examples', link: '/syntax/examples' },
       ],
     },
diff --git a/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts b/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts
index e9a038ec4c..dd55d67826 100644
--- a/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts
+++ b/packages/mermaid/src/docs/.vitepress/theme/mermaid.ts
@@ -1,9 +1,10 @@
 import mermaid, { type MermaidConfig } from 'mermaid';
 import mindmap from '@mermaid-js/mermaid-mindmap';
+// import timeline from '@mermaid-js/mermaid-timeline';
 
 const init = (async () => {
   try {
-    await mermaid.registerExternalDiagrams([mindmap]);
+    await mermaid.registerExternalDiagrams([mindmap, timeline]);
   } catch (e) {
     console.error(e);
   }
diff --git a/packages/mermaid/src/docs/syntax/timeline.md b/packages/mermaid/src/docs/syntax/timeline.md
new file mode 100644
index 0000000000..76fdb5e60d
--- /dev/null
+++ b/packages/mermaid/src/docs/syntax/timeline.md
@@ -0,0 +1,294 @@
+# Timeline Diagram
+
+> Timeline: This is an experimental diagram for now. The syntax and properties can change in future releases. The syntax is stable except for the icon integration which is the experimental part.
+
+"A timeline is a type of diagram used to illustrate a chronology of events, dates, or periods of time. It is usually presented graphically to indicate the passing of time, and it is usually organized chronologically. A basic timeline presents a list of events in chronological order, usually using dates as markers. A timeline can also be used to show the relationship between events, such as the relationship between the events of a person's life. A timeline can also be used to show the relationship between events, such as the relationship between the events of a person's life." Wikipedia
+
+### An example of a timeline.
+
+```mermaid
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook
+         : Google
+    2005 : Youtube
+    2006 : Twitter
+```
+
+## Syntax
+
+The syntax for creating Timeline diagram is simple. You always start with the `timeline` keyword to let mermaid know that you want to create a timeline diagram.
+
+After that there is a possibility to add a title to the timeline. This is done by adding a line with the keyword `title` followed by the title text.
+
+Then you add the timeline data, where you always start with a time period, followed by a colon and then the text for the event. Optionally you can add a second colon and then the text for the event. So, you can have one or more events per time period.
+
+```json
+{time period} : {event}
+```
+
+or
+
+```json
+{time period} : {event} : {event}
+```
+
+or
+
+```json
+{time period} : {event}
+              : {event}
+              : {event}
+```
+
+NOTE: Both time period and event are simple text, and not limited to numbers.
+
+Let us look at the syntax for the example above.
+
+```mermaid-example
+timeline
+    title History of Social Media Platform
+    2002 : LinkedIn
+    2004 : Facebook : Google
+    2005 : Youtube
+    2006 : Twitter
+```
+
+In this way we can use a text outline to generate a timeline diagram.
+The sequence of time period and events is important, as it will be used to draw the timeline. The first time period will be placed at the left side of the timeline, and the last time period will be placed at the right side of the timeline.
+
+Similarly, the first event will be placed at the top for that specific time period, and the last event will be placed at the bottom.
+
+## Grouping of time periods in sections/ages
+
+You can group time periods in sections/ages. This is done by adding a line with the keyword `section` followed by the section name.
+
+All subsequent time periods will be placed in this section until a new section is defined.
+
+If no section is defined, all time periods will be placed in the default section.
+
+Let us look at an example, where we have grouped the time periods in sections.
+
+```mermaid-example
+timeline
+    title Timeline of Industrial Revolution
+    section 17th-20th century
+        Industry 1.0 : Machinery, Water power, Steam 
power
+        Industry 2.0 : Electricity, Internal combustion engine, Mass production
+        Industry 3.0 : Electronics, Computers, Automation
+    section 21st century
+        Industry 4.0 : Internet, Robotics, Internet of Things
+        Industry 5.0 : Artificial intelligence, Big data,3D printing
+```
+
+As you can see, the time periods are placed in the sections, and the sections are placed in the order they are defined.
+
+All time periods and events under a given section follow a similar color scheme. This is done to make it easier to see the relationship between time periods and events.
+
+## Wrapping of text for long time-periods or events
+
+By default, the text for time-periods and events will be wrapped if it is too long. This is done to avoid that the text is drawn outside the diagram.
+
+You can also use `
` to force a line break.
+
+Let us look at another example, where we have a long time period, and a long event.
+
+```mermaid-example
+timeline
+        title England's History Timeline
+        section Stone Age
+          7600 BC : Britain's oldest known house was built in Orkney, Scotland
+          6000 BC : Sea levels rise and Britain becomes an island.
 The people who live here are hunter-gatherers.
+        section Broze Age
+          2300 BC : People arrive from Europe and settle in Britain. 
They bring farming and metalworking.
+                  : New styles of pottery and ways of burying the dead appear.
+          2200 BC : The last major building works are completed at Stonehenge.
 People now bury their dead in stone circles.
+                  : The first metal objects are made in Britain.Some other nice things happen. it is a good time to be alive.
+
+```
+
+```mermaid-example
+timeline
+        title MermaidChart 2023 Timeline
+        section 2023 Q1 
 Release Personal Tier
+          Buttet 1 : sub-point 1a : sub-point 1b
+               : sub-point 1c
+          Bullet 2 : sub-point 2a : sub-point 2b
+        section 2023 Q2 
 Release XYZ Tier
+          Buttet 3 : sub-point 
 3a : sub-point 3b
+               : sub-point 3c
+          Bullet 4 : sub-point 4a : sub-point 4b
+```
+
+## Styling of time periods and events
+
+As explained earlier, each section has a color scheme, and each time period and event under a section follow the similar color scheme.
+
+However, if there is no section defined, then we have two possibilities:
+
+1. Style time periods individually, i.e. each time period(and its coressponding events) will have its own color scheme. This is the DEFAULT behavior.
+
+```mermaid-example
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+
+```
+
+Note that this is no, section defined, and each time period and its corresponding events will have its own color scheme.
+
+2. Disable the multiColor option using the `disableMultiColor` option. This will make all time periods and events follow the same color scheme.
+
+You will need to add this option either via mermaid.intialize function or directives.
+
+```javascript
+mermaid.initialize({
+        theme: 'base',
+        startOnLoad: true,
+        logLevel: 0,
+        timeline: {
+          disableMulticolor: false,
+        },
+        ...
+        ...
+```
+
+let us look at same example, where we have disabled the multiColor option.
+
+```mermaid-example
+   %%{init: { 'logLevel': 'debug', 'theme': 'base', 'timeline': {'disableMulticolor': true}}}%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+
+```
+
+### Customizing Color scheme
+
+You can customize the color scheme using the `cScale0` to `cScale11` theme variables. Mermaid allows you to set unique colors for up-to 12, where `cScale0` variable will drive the value of the first section or time-period, `cScale1` will drive the value of the second section and so on.
+In case you have more than 12 sections, the color scheme will start to repeat.
+
+NOTE: Default values for these theme variables are picked from the selected theme. If you want to override the default values, you can use the `initialize` call to add your custom theme variable values.
+
+Example:
+
+Now let's override the default values for the `cScale0` to `cScale2` variables:
+
+```mermaid-example
+    %%{init: { 'logLevel': 'debug', 'theme': 'default' , 'themeVariables': {
+              'cScale0': '#ff0000',
+              'cScale1': '#00ff00',
+              'cScale2': '#0000ff'
+       } } }%%
+       timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+
+```
+
+See how the colors are changed to the values specified in the theme variables.
+
+## Themes
+
+Mermaid supports a bunch of pre-defined themes which you can use to find the right one for you. PS: you can actually override an existing theme's variable to get your own custom theme going. Learn more about theming your diagram [here](../config/theming.md).
+
+The following are the different pre-defined theme options:
+
+- `base`
+- `forest`
+- `dark`
+- `default`
+- `neutral`
+
+**NOTE**: To change theme you can either use the `initialize` call or _directives_. Learn more about [directives](../config/directives.md)
+Let's put them to use, and see how our sample diagram looks in different themes:
+
+### Base Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'base' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Forest Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'forest' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Dark Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Default Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'default' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+### Neutral Theme
+
+```mermaid-example
+%%{init: { 'logLevel': 'debug', 'theme': 'neutral' } }%%
+    timeline
+        title History of Social Media Platform
+          2002 : LinkedIn
+          2004 : Facebook : Google
+          2005 : Youtube
+          2006 : Twitter
+          2007 : Tumblr
+          2008 : Instagram
+          2010 : Pinterest
+```
+
+You can also refer the implementation in the live editor [here](https://github.com/mermaid-js/mermaid-live-editor/blob/fcf53c98c25604c90a218104268c339be53035a6/src/lib/util/mermaid.ts) to see how the async loading is done.
diff --git a/packages/mermaid/src/docs/vite.config.ts b/packages/mermaid/src/docs/vite.config.ts
index 15652c21c6..356e9398ca 100644
--- a/packages/mermaid/src/docs/vite.config.ts
+++ b/packages/mermaid/src/docs/vite.config.ts
@@ -36,6 +36,10 @@ export default defineConfig({
         __dirname,
         '../../../mermaid-mindmap/dist/mermaid-mindmap.esm.min.mjs'
       ), // Use this one to build
+      // '@mermaid-js/mermaid-timeline': path.join(
+      //   __dirname,
+      //   '../../../mermaid-timeline/dist/mermaid-timeline.esm.min.mjs'
+      // ),
     },
   },
   server: {
diff --git a/packages/mermaid/src/mermaidAPI.ts b/packages/mermaid/src/mermaidAPI.ts
index 5d23671add..68db59b34f 100644
--- a/packages/mermaid/src/mermaidAPI.ts
+++ b/packages/mermaid/src/mermaidAPI.ts
@@ -32,6 +32,7 @@ import { MermaidConfig } from './config.type';
 import { evaluate } from './diagrams/common/common';
 import isEmpty from 'lodash-es/isEmpty.js';
 import { setA11yDiagramInfo, addSVGa11yTitleDescription } from './accessibility';
+import { parseDirective } from './directiveUtils';
 
 // diagram names that support classDef statements
 const CLASSDEF_DIAGRAMS = ['graph', 'flowchart', 'flowchart-v2', 'stateDiagram', 'stateDiagram-v2'];
@@ -778,83 +779,6 @@ const renderAsync = async function (
   return svgCode;
 };
 
-let currentDirective: { type?: string; args?: any } | undefined = {};
-
-const parseDirective = function (p: any, statement: string, context: string, type: string): void {
-  try {
-    if (statement !== undefined) {
-      statement = statement.trim();
-      switch (context) {
-        case 'open_directive':
-          currentDirective = {};
-          break;
-        case 'type_directive':
-          if (!currentDirective) {
-            throw new Error('currentDirective is undefined');
-          }
-          currentDirective.type = statement.toLowerCase();
-          break;
-        case 'arg_directive':
-          if (!currentDirective) {
-            throw new Error('currentDirective is undefined');
-          }
-          currentDirective.args = JSON.parse(statement);
-          break;
-        case 'close_directive':
-          handleDirective(p, currentDirective, type);
-          currentDirective = undefined;
-          break;
-      }
-    }
-  } catch (error) {
-    log.error(
-      `Error while rendering sequenceDiagram directive: ${statement} jison context: ${context}`
-    );
-    // @ts-ignore: TODO Fix ts errors
-    log.error(error.message);
-  }
-};
-
-const handleDirective = function (p: any, directive: any, type: string): void {
-  log.debug(`Directive type=${directive.type} with args:`, directive.args);
-  switch (directive.type) {
-    case 'init':
-    case 'initialize': {
-      ['config'].forEach((prop) => {
-        if (directive.args[prop] !== undefined) {
-          if (type === 'flowchart-v2') {
-            type = 'flowchart';
-          }
-          directive.args[type] = directive.args[prop];
-          delete directive.args[prop];
-        }
-      });
-      log.debug('sanitize in handleDirective', directive.args);
-      directiveSanitizer(directive.args);
-      log.debug('sanitize in handleDirective (done)', directive.args);
-      configApi.addDirective(directive.args);
-      break;
-    }
-    case 'wrap':
-    case 'nowrap':
-      if (p && p['setWrap']) {
-        p.setWrap(directive.type === 'wrap');
-      }
-      break;
-    case 'themeCss':
-      log.warn('themeCss encountered');
-      break;
-    default:
-      log.warn(
-        `Unhandled directive: source: '%%{${directive.type}: ${JSON.stringify(
-          directive.args ? directive.args : {}
-        )}}%%`,
-        directive
-      );
-      break;
-  }
-};
-
 /**
  * @param  options - Initial Mermaid options
  */
diff --git a/packages/mermaid/src/themes/theme-default.js b/packages/mermaid/src/themes/theme-default.js
index 969551ee6b..391c0298f1 100644
--- a/packages/mermaid/src/themes/theme-default.js
+++ b/packages/mermaid/src/themes/theme-default.js
@@ -122,6 +122,7 @@ class Theme {
   updateColors() {
     /* Color Scale */
     /* Each color-set will have a background, a foreground and a border color */
+
     this.cScale0 = this.cScale0 || this.primaryColor;
     this.cScale1 = this.cScale1 || this.secondaryColor;
     this.cScale2 = this.cScale2 || this.tertiaryColor;
@@ -141,7 +142,6 @@ class Theme {
       this['cScale' + i] = darken(this['cScale' + i], 10);
       this['cScalePeer' + i] = this['cScalePeer' + i] || darken(this['cScale' + i], 25);
     }
-
     // Setup the inverted color for the set
     for (let i = 0; i < this.THEME_COLOR_LIMIT; i++) {
       this['cScaleInv' + i] = this['cScaleInv' + i] || adjust(this['cScale' + i], { h: 180 });
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8d2c0a4bd2..9613048288 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -349,6 +349,22 @@ importers:
         specifier: ^3.0.2
         version: 3.0.2
 
+  packages/mermaid-timeline:
+    dependencies:
+      d3:
+        specifier: ^7.0.0
+        version: 7.6.1
+      khroma:
+        specifier: ^2.0.0
+        version: 2.0.0
+    devDependencies:
+      concurrently:
+        specifier: ^7.4.0
+        version: 7.5.0
+      rimraf:
+        specifier: ^3.0.2
+        version: 3.0.2
+
   tests/webpack:
     dependencies:
       '@mermaid-js/mermaid-mindmap':