Ir para o conteúdo principal
Version: Canary 🚧

MDX e React

Usando JSX no Markdown

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

note

While Docusaurus parses both .md and .mdx files using MDX, some of the syntaxes are treated slightly differently by third-party tools. Para a análise mais precisa e melhor suporte a editores, recomendamos usar a extensão .mdx para arquivos que contenham sintaxe MDX.

Confira a documentação MDX para ver quais outras coisas legais que você consegue fazer com o MDX.

Exporting components

To define any custom component within an MDX file, you have to export it: only paragraphs that start with export will be parsed as components instead of prose.

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.

Eu posso escrever **Markdown** ao lado de meu _JSX_!

Observe como ele renderiza tanto o markup do seu componente React como a sintaxe Markdown:

http://localhost:3000
Docusaurus green and Facebook blue are my favorite colors.

Eu posso escrever Markdown ao lado de meu JSX!

MDX is JSX

Since all doc files are parsed using MDX, anything that looks like HTML is actually JSX. Portanto, se você precisar criar um estilo embutido em um componente, siga o tipo JSX e forneça objetos de estilo.

/* Instead of this: */
<span style="background-color: red">Foo</span>
/* Use this: */
<span style={{backgroundColor: 'red'}}>Foo</span>

Este comportamento é diferente do Docusaurus 1. Veja também Migrando da v1 para a v2.

In addition, MDX is not 100% compatible with CommonMark. Use the MDX playground to ensure that your syntax is valid MDX.

Importing components

You can also import your own components defined in other files or third-party components installed via npm.

<!-- Docusaurus theme component -->
import TOCInline from '@theme/TOCInline';
<!-- External component -->
import Button from '@mui/material/Button';
<!-- Custom component -->
import BrowserWindow from '@site/src/components/BrowserWindow';
tip

The @site alias points to your website's directory, usually where the docusaurus.config.js file is. Using an alias instead of relative paths ('../../src/components/BrowserWindow') saves you from updating import paths when moving files around, or when versioning docs and translating.

While declaring components within Markdown is very convenient for simple cases, it becomes hard to maintain because of limited editor support, risks of parsing errors, and low reusability. Use a separate .js file when your component involves complex JS logic:

src/components/Highlight.js
import React from 'react';

export default function Highlight({children, color}) {
return (
<span
style={{
backgroundColor: color,
borderRadius: '2px',
color: '#fff',
padding: '0.2rem',
}}>
{children}
</span>
);
}
markdown-file.mdx
import Highlight from '@site/src/components/Highlight';

<Highlight color="#25c2a0">Docusaurus green</Highlight>
tip

If you use the same component across a lot of files, you don't need to import it everywhere—consider adding it to the global scope. See below

MDX component scope

Apart from importing a component and exporting a component, a third way to use a component in MDX is to register it to the global scope, which will make it automatically available in every MDX file, without any import statements.

For example, given this MDX file:

- a
- list!

And some <highlight>custom markup</highlight>...

It will be compiled to a React component containing ul, li, p, and highlight tags. Now, you can optionally provide your own implementation for any of these tags in the form of React components. (highlight isn't even an intrinsic element: it needs an implementation!)

In Docusaurus, this MDX component scope is provided by the @theme/MDXComponents component. It's not a React component, per se, unlike most other exports under the @theme/ alias: it is a record from tag names like ul and img to their custom implementations.

If you swizzle this component, you will find all tags that have been re-implemented, and you can further customize our implementation by swizzling the respective sub-component, like @theme/MDXComponents/Head (which is used to implement the <head> feature).

If you want to register extra tag names (like the <highlight> tag above), you should consider wrapping @theme/MDXComponents, so you don't have to maintain all the existing mappings. Since the swizzle CLI doesn't allow wrapping non-component files yet, you should manually create the wrapper:

src/theme/MDXComponents.js
import React from 'react';
// Import the original mapper
import MDXComponents from '@theme-original/MDXComponents';
import Highlight from '@site/src/components/Highlight';

export default {
// Re-use the default mapping
...MDXComponents,
// Map the "highlight" tag to our <Highlight /> component!
// `Highlight` will receive all props that were passed to `highlight` in MDX
highlight: Highlight,
};

And now, you can freely use <highlight> in every page, without writing the import statement:

I can conveniently use <highlight color="#25c2a0">Docusaurus green</highlight> everywhere!
http://localhost:3000

I can conveniently use Docusaurus green everywhere!

info

We use lower-case tag names like highlight to "pretend" that they are intrinsic elements, but you can use capitalized ones like Highlight as well.

caution

This feature is powered by a wrapper provider. If you are importing Markdown in a React page, you have to supply this provider yourself through the MDXContent theme component.

src/pages/index.js
import React from 'react';
import FeatureDisplay from './_featureDisplay.mdx';
import MDXContent from '@theme/MDXContent';

export default function LandingPage() {
return (
<div>
<MDXContent>
<FeatureDisplay />
</MDXContent>
</div>
);
}

If you don't wrap your imported MDX with MDXContent, the global scope will not be available.

Markdown and JSX interoperability

Docusaurus v2 is using MDX v1, which has a lot of known cases where the content fails to be correctly parsed as Markdown. Use the MDX playground to ensure that your syntax is valid MDX.

Samples of parsing failures

A paragraph starting with a JSX tag will be seen entirely as a JSX string:

<span style={{color: 'red'}}>Highlighted text</span> but afterwards _Markdown_ **doesn't work**
http://localhost:3000
Highlighted text but afterwards _Markdown_ **doesn't work**

Markdown within a JSX tag never works:

<span style={{color: 'red'}}>**Bold doesn't work**</span>
http://localhost:3000
**Bold doesn't work**

Text immediately below a JSX tag will be seen as JSX text:

<div style={{color: 'red'}}>
**Bold still doesn't work**
</div>
http://localhost:3000
**Bold still doesn't work**

Markdown text indented by four spaces will be seen as a code block:

<div style={{color: 'red'}}>

You may think I'm just some text...

</div>
http://localhost:3000
You may think I'm just some text...

Importando trechos de código

Você não pode apenas importar um arquivo contendo uma definição de componente, mas também importar qualquer arquivo de código como texto bruto e, em seguida, inseri-lo em um bloco de código, graças ao Webpack raw-loader. In order to use raw-loader, you first need to install it in your project:

npm install --save raw-loader

Agora você pode importar trechos de código a partir de outro arquivo da seguinte forma:

myMarkdownFile.mdx
import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./myComponent';

<CodeBlock 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>
);
}

See using code blocks in JSX for more details of the <CodeBlock> component.

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 to interpolate the imported text here.

warning

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

Importando Markdown

Você pode usar arquivos Markdown como componentes e importá-los em outro lugar, em arquivos Markdown ou nas páginas React.

By convention, using the _ filename prefix will not create any doc page and means the Markdown file is a "partial", to be imported by other files.

_markdown-partial-example.mdx
<span>Olá {props.name}</span>

Este é um texto de alguns conteúdos de `_markdown-partial-example.mdx`.
someOtherDoc.mdx
import PartialExample from './_markdown-partial-example.mdx';

<PartialExample name="Sebastien" />
http://localhost:3000
Hello Sebastien

Este é um texto com parte do conteúdo de _markdown-partial-example.md.

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

caution

Currently, the table of contents does not contain the imported Markdown headings. Essa é uma limitação técnica que estamos tentando resolver (issue).

Available exports

Within the MDX page, the following variables are available as globals:

  • frontMatter: the front matter as a record of string keys and values;
  • toc: the table of contents, as a tree of headings. See also Inline TOC for a more concrete use-case.
  • contentTitle: the Markdown title, which is the first h1 heading in the Markdown text. It's undefined if there isn't one (e.g. title specified in the front matter).
import TOCInline from '@theme/TOCInline';
import CodeBlock from '@theme/CodeBlock';

The table of contents for this page, serialized:

<CodeBlock className="language-json">{JSON.stringify(toc, null, 2)}</CodeBlock>

The front matter of this page:

<ul>
{Object.entries(frontMatter).map(([key, value]) => <li key={key}><b>{key}</b>: {value}</li>)}
</ul>

<p>The title of this page is: <b>{contentTitle}</b></p>
http://localhost:3000

The table of contents for this page, serialized:

[
{
"value": "Usando JSX no Markdown",
"id": "using-jsx-in-markdown",
"level": 2
},
{
"value": "Exporting components",
"id": "exporting-components",
"level": 3
},
{
"value": "Importing components",
"id": "importing-components",
"level": 3
},
{
"value": "MDX component scope",
"id": "mdx-component-scope",
"level": 3
},
{
"value": "Markdown and JSX interoperability",
"id": "markdown-and-jsx-interoperability",
"level": 3
},
{
"value": "Importando trechos de código",
"id": "importing-code-snippets",
"level": 2
},
{
"value": "Importando Markdown",
"id": "importing-markdown",
"level": 2
},
{
"value": "Available exports",
"id": "available-exports",
"level": 2
}
]

The front matter of this page:

  • id: react
  • description: Usando o poder do React nos documentos do Docusaurus Markdown, graças ao MDX
  • slug: /markdown-features/react

The title of this page is: MDX e React