From 34d1defd834e07b18ffc562e6806de38759450df Mon Sep 17 00:00:00 2001 From: Jeppe Reinhold Date: Wed, 25 Jan 2023 11:11:30 +0100 Subject: [PATCH 1/6] disable MDX loader for MD in Vite --- code/lib/builder-vite/src/plugins/mdx-plugin.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/lib/builder-vite/src/plugins/mdx-plugin.ts b/code/lib/builder-vite/src/plugins/mdx-plugin.ts index deedf25fa822..cc99399010d2 100644 --- a/code/lib/builder-vite/src/plugins/mdx-plugin.ts +++ b/code/lib/builder-vite/src/plugins/mdx-plugin.ts @@ -13,7 +13,7 @@ const isStorybookMdx = (id: string) => id.endsWith('stories.mdx') || id.endsWith * @see https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/recipes.md#csf-stories-with-arbitrary-mdx */ export async function mdxPlugin(options: Options): Promise { - const include = /\.mdx?$/; + const include = /\.mdx$/; const filter = createFilter(include); const addons = await options.presets.apply('addons', []); const docsOptions = From bece362f884077b55aa77fedb9c6fb7388261583 Mon Sep 17 00:00:00 2001 From: Jeppe Reinhold Date: Wed, 25 Jan 2023 11:19:34 +0100 Subject: [PATCH 2/6] remove transcludeMarkdown option --- code/addons/docs/src/preset.ts | 20 +------------------ .../core-server/src/__for-testing__/main.ts | 1 - 2 files changed, 1 insertion(+), 20 deletions(-) diff --git a/code/addons/docs/src/preset.ts b/code/addons/docs/src/preset.ts index 3b7ac4a87a7a..5d3cbd739ae6 100644 --- a/code/addons/docs/src/preset.ts +++ b/code/addons/docs/src/preset.ts @@ -25,7 +25,6 @@ async function webpack( /** @deprecated */ sourceLoaderOptions: any; csfPluginOptions: CsfPluginOptions | null; - transcludeMarkdown: boolean; jsxOptions?: JSXOptions; } /* & Parameters< typeof createCompiler @@ -38,7 +37,6 @@ async function webpack( const { csfPluginOptions = {}, jsxOptions = {}, - transcludeMarkdown = false, sourceLoaderOptions = null, configureJsx, mdxBabelOptions, @@ -75,22 +73,6 @@ async function webpack( const mdxLoader = require.resolve('@storybook/mdx2-csf/loader'); - let rules = module.rules || []; - if (transcludeMarkdown) { - rules = [ - ...rules.filter((rule: any) => rule.test?.toString() !== '/\\.md$/'), - { - test: /\.md$/, - use: [ - { - loader: mdxLoader, - options: mdxLoaderOptions, - }, - ], - }, - ]; - } - const result = { ...webpackConfig, plugins: [ @@ -102,7 +84,7 @@ async function webpack( module: { ...module, rules: [ - ...rules, + ...module.rules, { test: /(stories|story)\.mdx$/, use: [ diff --git a/code/lib/core-server/src/__for-testing__/main.ts b/code/lib/core-server/src/__for-testing__/main.ts index 883637275c82..5eaf65a45fa9 100644 --- a/code/lib/core-server/src/__for-testing__/main.ts +++ b/code/lib/core-server/src/__for-testing__/main.ts @@ -14,7 +14,6 @@ const config: StorybookConfig = { { name: '@storybook/addon-docs', options: { - transcludeMarkdown: true, sourceLoaderOptions: null, }, }, From 2187b314790d52941169c6eedf804e26ea823b1a Mon Sep 17 00:00:00 2001 From: Jeppe Reinhold Date: Wed, 25 Jan 2023 11:22:20 +0100 Subject: [PATCH 3/6] add support for ?raw imports in webpack5 builder --- .../builder-webpack5/src/preview/base-webpack.config.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/code/lib/builder-webpack5/src/preview/base-webpack.config.ts b/code/lib/builder-webpack5/src/preview/base-webpack.config.ts index 62ba0d8ed50b..8a2d60743661 100644 --- a/code/lib/builder-webpack5/src/preview/base-webpack.config.ts +++ b/code/lib/builder-webpack5/src/preview/base-webpack.config.ts @@ -74,6 +74,13 @@ export async function createDefaultWebpackConfig( : 'static/media/[path][name][ext]', }, }, + { + // any imports from './some-file.md?raw' will be imported as raw string + // see https://webpack.js.org/guides/asset-modules/#replacing-inline-loader-syntax + // used to support import raw .md files in MDX + resourceQuery: /raw/, + type: 'asset/source', + }, ], }, resolve: { From 9a036c1178c10a76c9567d0d0d3457bc461c2529 Mon Sep 17 00:00:00 2001 From: Jeppe Reinhold Date: Wed, 25 Jan 2023 21:01:48 +0100 Subject: [PATCH 4/6] make eslint ignore ?raw imports --- scripts/.eslintrc.js | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/.eslintrc.js b/scripts/.eslintrc.js index fe8ebf3eb80c..90f67a53fbb7 100644 --- a/scripts/.eslintrc.js +++ b/scripts/.eslintrc.js @@ -20,6 +20,7 @@ module.exports = { }, ], 'eslint-comments/disable-enable-pair': ['error', { allowWholeFile: true }], + 'import/no-unresolved': ['error', { ignore: ['\\?raw$'] }], }, overrides: [ { From cb701f95eae0b5f7994ec22f7c22ff34ced903d7 Mon Sep 17 00:00:00 2001 From: Jeppe Reinhold Date: Thu, 26 Jan 2023 02:01:58 +0100 Subject: [PATCH 5/6] don't change eslint rule anyway --- scripts/.eslintrc.js | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/.eslintrc.js b/scripts/.eslintrc.js index 90f67a53fbb7..fe8ebf3eb80c 100644 --- a/scripts/.eslintrc.js +++ b/scripts/.eslintrc.js @@ -20,7 +20,6 @@ module.exports = { }, ], 'eslint-comments/disable-enable-pair': ['error', { allowWholeFile: true }], - 'import/no-unresolved': ['error', { ignore: ['\\?raw$'] }], }, overrides: [ { From 1a0ce202b75542562ef332c94905f2b300148ce1 Mon Sep 17 00:00:00 2001 From: Jeppe Reinhold Date: Thu, 26 Jan 2023 02:16:33 +0100 Subject: [PATCH 6/6] migration notes for plain md changes --- MIGRATION.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 55cabfd3fb17..55f79035a8dc 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -15,6 +15,7 @@ - [Stories glob matches MDX files](#stories-glob-matches-mdx-files) - [Add strict mode](#add-strict-mode) - [Babel mode v7 exclusively](#babel-mode-v7-exclusively) + - [Importing plain markdown files with `transcludeMarkdown` has changed](#importing-plain-markdown-files-with-transcludemarkdown-has-changed) - [7.0 feature flags removed](#70-feature-flags-removed) - [Core addons](#core-addons) - [Removed auto injection of @storybook/addon-actions decorator](#removed-auto-injection-of-storybookaddon-actions-decorator) @@ -540,6 +541,21 @@ npx sb@next babelrc This will create a `.babelrc.json` file. This file includes a bunch of babel plugins, so you may need to add new package devDependencies accordingly. +#### Importing plain markdown files with `transcludeMarkdown` has changed + +The `transcludeMarkdown` option in `addon-docs` have been removed, and the automatic handling of `.md` files in Vite projects have also been disabled. + +Instead `.md` files can be imported as plain strings by adding the `?raw` suffix to the import. In an MDX file that would look like this: + +``` +import ReadMe from './README.md?raw'; + +... + +{ReadMe} + +``` + #### 7.0 feature flags removed Storybook uses temporary feature flags to opt-in to future breaking changes or opt-in to legacy behaviors. For example: @@ -790,7 +806,7 @@ We've renamed many of the parameters that control docs rendering for consistency Previously `.stories.mdx` files were used to both define and document stories. In 7.0, we have deprecated defining stories in MDX files, and consequently have changed the suffix to simply `.mdx`. Our default `stories` glob in `main.js` will now match such files -- if you want to write MDX files that do not appear in Storybook, you may need to adjust the glob accordingly. -If you were using `.stories.mdx` files to write stories, we encourage you to move the stories to a CSF file, and *attach* an `.mdx` file to that CSF file to document them. You can use the `Meta` block to attach a MDX file to a CSF file, and the `Story` block to render the stories: +If you were using `.stories.mdx` files to write stories, we encourage you to move the stories to a CSF file, and _attach_ an `.mdx` file to that CSF file to document them. You can use the `Meta` block to attach a MDX file to a CSF file, and the `Story` block to render the stories: ```mdx import { Meta, Story } from '@storybook/blocks'; @@ -805,7 +821,6 @@ You can create as many docs entries as you like for a given component. Note that By default docs entries are listed first for the component. You can sort them using story sorting. - #### Unattached docs files In Storybook 6.x, to create a unattached docs MDX file (that is, one not attached to story or a CSF file), you'd have to create a `.stories.mdx` file, and describe its location with the `Meta` doc block: @@ -818,14 +833,13 @@ import { Meta } from '@storybook/addon-docs'; In 7.0, things are a little simpler -- you should call the file `.mdx` (drop the `.stories`). This will mean behind the scenes there is no story attached to this entry. You may also drop the `title` and use autotitle (and leave the `Meta` component out entirely, potentially). - #### Doc Blocks Additionally to changing the docs information architecture, we've updated the API of the doc blocks themselves to be more consistent and future proof. **General changes** -- Each block now uses `of={}` as a primary API -- where the argument to the `of` prop is a CSF or story *export*. +- Each block now uses `of={}` as a primary API -- where the argument to the `of` prop is a CSF or story _export_. - When you've attached to a CSF file (with the `Meta` block, or in Autodocs), you can drop the `of` and the block will reference the first story or the CSF file as a whole. @@ -871,7 +885,7 @@ Referencing stories by `id="xyz--abc"` is deprecated and should be replaced with ##### Source block -The source block now references a single story, the component, or a CSF file itself via the `of={}` parameter. +The source block now references a single story, the component, or a CSF file itself via the `of={}` parameter. Referencing stories by `id="xyz--abc"` is deprecated and should be replaced with `of={}` as above. Referencing multiple stories via `ids={["xyz--abc"]}` is now deprecated and should be avoided (instead use two source blocks). @@ -884,6 +898,7 @@ The `ArgsTable` block is now deprecated, and two new blocks: `ArgsTypes` and `Co - `` will render the controls for a story (or the primary story if `of` is omitted and the MDX file is attached). The following props are not supported in the new blocks: + - `components` - to render more than one component in a single table - `showComponent` to show the component's props as well as the story's args - the `subcomponents` annotation to show more components on the table. @@ -892,7 +907,6 @@ The following props are not supported in the new blocks: - `story="."` to reference the current story (this no longer makes sense in Docs 2). - `story="name"` to reference a story (use `of={}`). - #### Configuring Autodocs As in 6.x, you can override the docs container to configure docs further. This is the container that each docs entry is rendered inside: @@ -907,7 +921,7 @@ export const parameters = { } ``` -Note that the container must be implemented as a *React component*. +Note that the container must be implemented as a _React component_. You likely want to use the `DocsContainer` component exported by `@storybook/blocks` and consider the following examples: