diff --git a/addons/docs/docs/recipes.md b/addons/docs/docs/recipes.md
index 9c18bb74a5a3..793203738bf1 100644
--- a/addons/docs/docs/recipes.md
+++ b/addons/docs/docs/recipes.md
@@ -6,6 +6,7 @@
- [Pure MDX Stories](#pure-mdx-stories)
- [Mixed CSF / MDX Stories](#mixed-csf--mdx-stories)
- [CSF Stories with MDX Docs](#csf-stories-with-mdx-docs)
+- [CSF Stories with arbitrary MDX](#csf-stories-with-arbitrary-mdx)
- [Mixing storiesOf with CSF/MDX](#mixing-storiesof-with-csfmdx)
- [Migrating from notes/info addons](#migrating-from-notesinfo-addons)
- [Exporting documentation](#exporting-documentation)
@@ -31,6 +32,55 @@ The only limitation is that your exported titles (CSF: `default.title`, MDX `Met
Perhaps you want to write your stories in CSF, but document them in MDX? Here's how to do that:
+**Button.stories.js**
+
+```js
+import React from 'react';
+import { Button } from './Button';
+
+export default {
+ title: 'Demo/Button',
+ component: Button,
+ includeStories: [], // or don't load this file at all
+};
+
+export const basic = () => ;
+basic.story = {
+ parameters: { foo: 'bar' },
+};
+```
+
+**Button.stories.mdx**
+
+```md
+import { Meta, Story } from '@storybook/addon-docs/blocks';
+import \* as stories from './Button.stories.js';
+import { SomeComponent } from 'path/to/SomeComponent';
+
+
+
+# Button
+
+I can define a story with the function imported from CSF:
+
+{stories.basic()}
+
+And I can also embed arbitrary markdown & JSX in this file.
+
+
+```
+
+What's happening here:
+
+- Your stories are defined in CSF, but because of `includeStories: []`, they are not actually added to Storybook.
+- The MDX file is adding the stories to Storybook, and using the story function defined in CSF.
+- The MDX loader is using story metadata from CSF, such as name, decorators, parameters, but will give giving preference to anything defined in the MDX file.
+- The MDX file is using the Meta `default` defined in the CSF.
+
+## CSF Stories with arbitrary MDX
+
+We recommend [MDX Docs](#csf-stories-with-mdx-docs) as the most ergonomic way to annotate CSF stories with MDX. There's also a second option if you want to annotate your CSF with arbitrary markdown:
+
**Button.mdx**
```md