diff --git a/packages/runtime/readme.md b/packages/runtime/readme.md
index 7616ad3d3..d7e239a72 100644
--- a/packages/runtime/readme.md
+++ b/packages/runtime/readme.md
@@ -25,14 +25,25 @@ npm i -S @mdx-js/runtime
 import React from 'react'
 import MDX from '@mdx-js/runtime'
 
+// Provide custom components for markdown elements
 const components = {
   h1: props => <h1 style={{ color: 'tomato' }} {...props} />
 }
 
-const mdx = '# Hello, world!'
+// Provide custom components that will be referenced as JSX
+// in the markdown string
+const scope = {
+  Demo: props => <h1>This is a demo component</h1>
+}
+
+const mdx = '
+# Hello, world!
+
+<Demo />
+'
 
 export default () => (
-  <MDX components={components}>{mdx}</MDX>
+  <MDX components={components} scope={scope}>{mdx}</MDX>
 )
 ```