diff --git a/docs/breaking-changes.asciidoc b/docs/breaking-changes.asciidoc
new file mode 100644
index 0000000000000..699da3c2d574f
--- /dev/null
+++ b/docs/breaking-changes.asciidoc
@@ -0,0 +1,12 @@
+[[breaking-changes]]
+== Breaking Changes
+
+This section discusses the changes that you need to be aware of when migrating
+your application from one version of Kibana to another.
+
+[[breaking-changes-5.0]]
+=== Breaking changes in 5.0
+* {k4pull}8013[Pull Request 8013]: Kibana binds to localhost by default
+* {k4pull}7855[Pull Request 7855]: Markdown headers require a space between the final hash and title
+* {k4pull}7308[Pull Request 7308]: Debian and rpm packages install assets to `/usr/share/kibana`, and configuration to `/etc/kibana`
+* {k4pull}6402[Pull Request 6402]: The plugin installer now has its own executable, it can be found at `/bin/kibana-plugin`
\ No newline at end of file
diff --git a/docs/index.asciidoc b/docs/index.asciidoc
index 245adb653cf4b..5b7556e9a0f26 100644
--- a/docs/index.asciidoc
+++ b/docs/index.asciidoc
@@ -16,6 +16,8 @@ include::setup.asciidoc[]
 
 include::getting-started.asciidoc[]
 
+include::breaking-changes.asciidoc[]
+
 include::plugins.asciidoc[]
 
 include::access.asciidoc[]