Markdown

Markdown 块允许你在 MDX 文件中导入和包含纯 markdown。

Screenshot of Markdown block

导入 markdown 文件时，重要的是在导入路径上使用 ?raw 后缀，以确保内容按原样导入，而不是被解析。

README.md

# Button
 
Primary UI component for user interaction
 
```js
import { Button } from "@storybook/design-system";
```

Header.mdx

// DON'T do this, will error
import ReadMe from './README.md';
// DO this, will work
import ReadMe from './README.md?raw';
 
import { Markdown } from '@storybook/addon-docs/blocks';
 
# A header 
 
<Markdown>{ReadMe}</Markdown>

Markdown

import { Markdown } from '@storybook/addon-docs/blocks';

Markdown 使用以下 props 进行配置：

`children`

类型：string

提供要解析和显示的 markdown 格式的字符串。

`options`

指定传递给底层 markdown-to-jsx 库的选项。

为什么不直接导入 markdown？

从纯粹的技术角度来看，我们可以像这样直接在 MDX 文件中包含导入的 markdown：

{/* THIS WON'T WORK, THIS IS TO DEMONSTRATE AN ERROR */}
 
import ReadMe from './README.md';
 
# A header 
 
{ReadMe}

但是，纯 markdown 和 MDX2 之间存在细微的语法差异。MDX2 更严格，会将某些内容解释为 JSX 表达式。以下是一个完全有效的 markdown 文件的示例，如果直接由 MDX2 处理，它将会出错：

# A header
 
{ this is valid in a plain markdown file, but MDX2 will try to evaluate this as an expression }
 
<This is also valid, but MDX2 thinks this is a JSX component />

此外，MDX2 会将所有字符串中的换行符包装在 p 标签或类似标签中，这意味着内容在纯 .md 文件和 .mdx 文件之间的渲染方式会有所不同。

# A header
 
<div>
  Some text
</div>
 
The example above will remain as-is in plain markdown, but MDX2 will compile it to:
 
# A header
 
<div>
  <p>Some text</p>
</div>