使用 React

Using JSX in Markdown

Docusaurus has built-in support for MDX, which allows you to write JSX within your Markdown files and render them as React components.

note

While both .md and .mdx files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the .mdx extension for files containing MDX syntax.

Try this block here:

export const Highlight = ({children, color}) => (  <span    style={{      backgroundColor: color,      borderRadius: '2px',      color: '#fff',      padding: '0.2rem',    }}>    {children}  </span>);
<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
I can write **Markdown** alongside my _JSX_!

Notice how it renders both the markup from your React component and the Markdown syntax:

http://localhost:3000

Docusaurus green and Facebook blue are my favorite colors.

I can write Markdown alongside my JSX!

You can also import your own components defined in other files or third-party components installed via npm! Check out the MDX docs to see what other fancy stuff you can do with MDX.

caution

Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also Migrating from v1 to v2.

Importing code snippets

You can not only import a file containing a component definition, but also import any code file as raw text, and then insert it in a code block, thanks to Webpack raw-loader.

myMarkdownFile.mdx

import CodeBlock from '@theme/CodeBlock';import MyComponentSource from '!!raw-loader!./myComponent';
<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>;

http://localhost:3000

/** * Copyright (c) Facebook, Inc. and its affiliates. * * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. */
import React, {useState} from 'react';
export default function MyComponent() {  const [bool, setBool] = useState(false);  return (    <div>      <p>MyComponent rendered !</p>      <p>bool={bool ? 'true' : 'false'}</p>      <p>        <button onClick={() => setBool((b) => !b)}>toggle bool</button>      </p>    </div>  );}

note

You have to use <CodeBlock> rather than the Markdown triple-backtick ```, because the latter will ship out any of its content as-is, but you want JSX to insert the imported text here.

warning

This feature is experimental and might be subject to API breaking changes in the future.

Importing Markdown

You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages. Below we are importing from another file and inserting it as a component.

import Intro from './markdown-features-intro.mdx';
<Intro />;

http://localhost:3000

文档是您产品向用户展示的门面之一。 文从字顺、层次清晰的文章有助于用户快速了解您的产品。 我们的一致目标是帮助用户尽快找到所需要的信息。

Docusaurus 2 使用现代化工具来帮助您轻松撰写交互式文档。 您可以嵌入 React 组件，亦或是搭建用户可交互的在线代码编辑块。 就用代码呈现您的灵光一现，捕获您受众的心吧！ 这可能是吸引潜在用户的最有效的方式。

本章节中，我们将向您介绍我们认为能帮助您构建强大文档的工具。 先让我们带您看个例子。

Markdown 是一种能让您撰写易读的格式化内容之语法。

Docusaurus 支持标准 Markdown 语法，且使用 MDX 作为解析引擎。因此，您不仅可以解析 Markdown 文件，还可以在其中渲染 React 组件。

important

本章节假定您使用 Docusaurus 官方的内容插件。

This way, you can reuse contents among multiple pages and avoid duplicating materials.

caution

The table-of-contents does not currently contain the imported Markdown headings. This is a technical limitation that we are trying to solve (issue).