Merge pull request #18247 from TheeMattOliver/patch-1

Update mdx.md
storybookjs · May 24, 2022 · af1bbc2 · af1bbc2
2 parents 4b849f9 + 7a2a78e
commit af1bbc2
Show file tree

Hide file tree

Showing 4 changed files with 62 additions and 1 deletion.
diff --git a/docs/snippets/common/mdx-changelog-stories.mdx.mdx b/docs/snippets/common/mdx-changelog-stories.mdx.mdx
@@ -0,0 +1,12 @@
+```md
+
+<!-- Changelog.stories.mdx -->
+
+import { Meta } from "@storybook/addon-docs";
+
+import Changelog from "../CHANGELOG.md";
+
+<Meta title="Changelog" />
+
+<Changelog />
+```
diff --git a/docs/snippets/common/storybook-main-enable-transcludemarkdown.js.mdx b/docs/snippets/common/storybook-main-enable-transcludemarkdown.js.mdx
@@ -0,0 +1,20 @@
+// .storybook/main.js|ts
+
+module.exports = {
+  stories: [
+    //👇 Changes the load order of our stories. First loads the Changelog page
+    '../src/Changelog.stories.mdx',
+    '../stories/**/*.stories.mdx', 
+    '../stories/**/*.stories.@(js|jsx|ts|tsx)'
+  ],
+  addons: [
+    '@storybook/addon-links',
+    '@storybook/addon-essentials',
+    {
+      name: '@storybook/addon-docs',
+      options: {
+        transcludeMarkdown: true, //👈 Set transcludeMarkdown to true
+      },
+    },
+  ],
+};
diff --git a/docs/writing-docs/changelog-mdx-md-transcludemarkdown-optimized.png b/docs/writing-docs/changelog-mdx-md-transcludemarkdown-optimized.png
diff --git a/docs/writing-docs/mdx.md b/docs/writing-docs/mdx.md
@@ -211,6 +211,35 @@ Write your documentation as you usually would, and your existing SCSS code block
 
 <!-- prettier-ignore-end -->
 
+### Creating a Changelog story
+
+One common use case for MDX-only docs stories is importing a project's `CHANGELOG.md` into an MDX story, so that users can easily refer to the CHANGELOG via a documentation node in Storybook.
+
+First, ensure that `transcludeMarkdown` is set to `true` in `main.js`:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/storybook-main-enable-transcludemarkdown.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+Then, import the markdown and treat the imported file as a component in the MDX file: 
+
+```mdx
+import { Meta } from "@storybook/addon-docs";
+
+import Changelog from "../CHANGELOG.md";
+
+<Meta title="Changelog" />
+
+<Changelog />
+```
+![Changelog markdown in an MDX story](./changelog-mdx-md-transcludemarkdown-optimized.png)
+
 ## Linking to other stories and pages
 
 When writing MDX, you may want to provide links to other stories or documentation pages and sections. You can use the `path` query string.
@@ -276,4 +305,4 @@ Update your Storybook configuration (in `.storybook/main.js|ts`) and add the `pr
   ]}
 />
 
-<!-- prettier-ignore-end -->
+<!-- prettier-ignore-end -->