diff --git a/addons/notes/README.md b/addons/notes/README.md
index 432ee9f6969..065789606c2 100644
--- a/addons/notes/README.md
+++ b/addons/notes/README.md
@@ -52,7 +52,7 @@ storiesOf('Component', module)
 
 #### Using Markdown
 
-To use markdown in your notes simply import a markdown file and use that in your note.
+To use markdown in your notes simply import a markdown file and use that in the `markdown` property of your note.
 
 ```js
 import { storiesOf } from '@storybook/react';
@@ -62,11 +62,11 @@ import someMarkdownText from './someMarkdownText.md';
 storiesOf('Component', module).add(
   'With Markdown',
   () => <Component />
-  { notes: someMarkdownText }
+  { notes: { markdown: someMarkdownText } }
 );
 ```
 
-If you want to use Github flavored markdown inline, use `notes: { markdownText: 'your md' }`:
+Similarly, if you want to use Github flavored markdown inline, use `notes: { markdownText: 'your md' }`:
 
 ```js
 import { storiesOf } from '@storybook/react';
diff --git a/examples/official-storybook/stories/addon-notes.stories.js b/examples/official-storybook/stories/addon-notes.stories.js
index 54d70f09f8c..9cc3606a048 100644
--- a/examples/official-storybook/stories/addon-notes.stories.js
+++ b/examples/official-storybook/stories/addon-notes.stories.js
@@ -32,7 +32,9 @@ storiesOf('Addons|Notes', module)
     notes:
       'This is the notes for a button. This is helpful for adding details about a story in a separate panel.',
   })
-  .add('withNotes rendering imported markdown', baseStory, { notes: markdownNotes })
+  .add('withNotes rendering imported markdown', baseStory, {
+    notes: { markdown: markdownNotes },
+  })
   .add('withNotes rendering inline, github-flavored markdown', baseStory, {
     notes: { markdown: markdownString },
   })