diff --git a/addons/notes/README.md b/addons/notes/README.md
index 719b6a6b2f1..3d65dbf83d8 100644
--- a/addons/notes/README.md
+++ b/addons/notes/README.md
@@ -3,18 +3,19 @@
 [![Build Status on CircleCI](https://circleci.com/gh/storybooks/storybook.svg?style=shield)](https://circleci.com/gh/storybooks/storybook)
 [![CodeFactor](https://www.codefactor.io/repository/github/storybooks/storybook/badge)](https://www.codefactor.io/repository/github/storybooks/storybook)
 [![Known Vulnerabilities](https://snyk.io/test/github/storybooks/storybook/8f36abfd6697e58cd76df3526b52e4b9dc894847/badge.svg)](https://snyk.io/test/github/storybooks/storybook/8f36abfd6697e58cd76df3526b52e4b9dc894847)
-[![BCH compliance](https://bettercodehub.com/edge/badge/storybooks/storybook)](https://bettercodehub.com/results/storybooks/storybook) [![codecov](https://codecov.io/gh/storybooks/storybook/branch/master/graph/badge.svg)](https://codecov.io/gh/storybooks/storybook)  
+[![BCH compliance](https://bettercodehub.com/edge/badge/storybooks/storybook)](https://bettercodehub.com/results/storybooks/storybook) [![codecov](https://codecov.io/gh/storybooks/storybook/branch/master/graph/badge.svg)](https://codecov.io/gh/storybooks/storybook)
 [![Storybook Slack](https://now-examples-slackin-rrirkqohko.now.sh/badge.svg)](https://now-examples-slackin-rrirkqohko.now.sh/)
 [![Backers on Open Collective](https://opencollective.com/storybook/backers/badge.svg)](#backers) [![Sponsors on Open Collective](https://opencollective.com/storybook/sponsors/badge.svg)](#sponsors)
 
-* * *
+---
 
 Storybook Addon Notes allows you to write notes (text or HTML) for your stories in [Storybook](https://storybook.js.org).
 
 This addon works with Storybook for:
-- [React](https://github.com/storybooks/storybook/tree/master/app/react)
-- [React Native](https://github.com/storybooks/storybook/tree/master/app/react-native)
-- [Vue](https://github.com/storybooks/storybook/tree/master/app/vue)
+
+* [React](https://github.com/storybooks/storybook/tree/master/app/react)
+* [React Native](https://github.com/storybooks/storybook/tree/master/app/react-native)
+* [Vue](https://github.com/storybooks/storybook/tree/master/app/vue)
 
 ![Storybook Addon Notes Demo](docs/demo.png)
 
@@ -29,7 +30,7 @@ Then create a file called `addons.js` in your storybook config.
 Add following content to it:
 
 ```js
-import '@storybook/addon-notes/register';
+import "@storybook/addon-notes/register";
 ```
 
 Then write your stories like this:
@@ -49,25 +50,48 @@ storiesOf('Component', module)
 To use markdown in your notes simply import a markdown file and use that in your note.
 
 ```js
-import { storiesOf } from '@storybook/react';
-import { withNotes } from '@storybook/addon-notes';
-import Component from './Component';
-import someMarkdownText from './someMarkdownText.md';
-
-storiesOf('Component', module)
-  .add('With Markdown', withNotes(someMarkdownText)(() => <Component/>));
+import { storiesOf } from "@storybook/react";
+import { withNotes } from "@storybook/addon-notes";
+import Component from "./Component";
+import someMarkdownText from "./someMarkdownText.md";
 
+storiesOf("Component", module).add("With Markdown", withNotes(someMarkdownText)(() => <Component />));
 ```
+
+If you want to use Github flavored markdown inline, use `withMarkdownNotes`:
+
+```js
+import { storiesOf } from "@storybook/react";
+import { withMarkdownNotes } from "@storybook/addon-notes";
+import Component from "./Component";
+
+storiesOf("Component", module).add(
+  "With Markdown",
+  withMarkdownNotes(`
+  # Hello World
+
+  This is some code showing usage of the component and other inline documentation
+
+  ~~~js
+  <div>
+    hello world!
+    <Component/>
+  </div>
+  ~~~
+  `)(() => <Component />)
+);
+```
+
 ### Deprecated API
+
 This API is slated for removal in 4.0
 
 ```js
-import { WithNotes } from '@storybook/addon-notes';
+import { WithNotes } from "@storybook/addon-notes";
 
-storiesOf('Addon Notes', module)
-  .add('using deprecated API', () => (
-    <WithNotes notes="Hello">
-      <BaseButton onClick={action('clicked')} label="😀 😎 👍 💯" />
-    </WithNotes>
-  ));
+storiesOf("Addon Notes", module).add("using deprecated API", () => (
+  <WithNotes notes="Hello">
+    <BaseButton onClick={action("clicked")} label="😀 😎 👍 💯" />
+  </WithNotes>
+));
 ```
diff --git a/addons/notes/package.json b/addons/notes/package.json
index 6824ef07bd6..e1286861599 100644
--- a/addons/notes/package.json
+++ b/addons/notes/package.json
@@ -21,6 +21,7 @@
   },
   "dependencies": {
     "babel-runtime": "^6.26.0",
+    "marked": "^0.3.12",
     "prop-types": "^15.6.0",
     "util-deprecate": "^1.0.2"
   },
diff --git a/addons/notes/src/index.js b/addons/notes/src/index.js
index 1fd5d328fcb..247210ab1e3 100644
--- a/addons/notes/src/index.js
+++ b/addons/notes/src/index.js
@@ -1,7 +1,18 @@
 import deprecate from 'util-deprecate';
 import addons from '@storybook/addons';
+import marked from 'marked';
 import { WithNotes as ReactWithNotes } from './react';
 
+export const withMarkdownNotes = text => {
+  const channel = addons.getChannel();
+
+  return getStory => context => {
+    // send the notes to the channel before the story is rendered
+    channel.emit('storybook/notes/add_notes', marked(text));
+    return getStory(context);
+  };
+};
+
 export const withNotes = textOrOptions => {
   const channel = addons.getChannel();
   const options = typeof textOrOptions === 'string' ? { text: textOrOptions } : textOrOptions;