diff --git a/README.md b/README.md
index b4dc8fa52..b970b2292 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,13 @@
 
 # mermaid [![Build Status](https://travis-ci.org/knsv/mermaid.svg?branch=master)](https://travis-ci.org/knsv/mermaid) [![Coverage Status](https://coveralls.io/repos/github/knsv/mermaid/badge.svg?branch=master)](https://coveralls.io/github/knsv/mermaid?branch=master) [![Join our Slack!](https://img.shields.io/static/v1?message=join%20chat&color=9cf&logo=slack&label=slack)](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) [![This project is using Percy.io for visual regression testing.](https://percy.io/static/images/percy-badge.svg)](https://percy.io/Mermaid/mermaid)
 
+## New diagrams in 8.4
+
+With version 8.4 class diagrams has got some new features, bug fixes and documentation. Another new feature in 8.4 is the new diagram
+type, state diagrams.
+
+![Image show the two new diagram types](./img/new-diagrams.png)
+
 ## Special note regarding version 8.2
 
 In version 8.2 a security improvement was introduced. A securityLevel configuration was introduced which sets the level of trust to be used on the parsed diagrams.
diff --git a/docs/README.md b/docs/README.md
index 621474feb..409d4f40c 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,12 +4,20 @@
 
 # mermaid
 
+## New diagrams in 8.4
+
+With version 8.4 class diagrams has got some new features, bug fixes and documentation. Another new feature in 8.4 is the new diagram
+type, state diagrams.
+
+![Image show the two new diagram types](./img/new-diagrams.png)
+
+
 ## Special note regarding version 8.2
 
 In version 8.2 a security improvement was introduced. A securityLevel configuration was introduced wich sets the level of trust to be used on the parsed diagrams.
 
 * **true**: (default) tags in text are encoded, click functionality is disabled
-* false: tags in text are allowed, click functionality is enabledClosed issues: 
+* false: tags in text are allowed, click functionality is enabledClosed issues:
 
 ⚠️ **Note** : This changes the default behaviour of mermaid so that after upgrade to 8.2, if the securityLevel is not configured, tags in flowcharts are encoded as tags and clicking is prohibited.
 
diff --git a/docs/img/new-diagrams.png b/docs/img/new-diagrams.png
new file mode 100644
index 000000000..dd9d0f14e
Binary files /dev/null and b/docs/img/new-diagrams.png differ
diff --git a/img/new-diagrams.png b/img/new-diagrams.png
new file mode 100644
index 000000000..dd9d0f14e
Binary files /dev/null and b/img/new-diagrams.png differ