Ir para o conteúdo principal
Version: 2.0.0-beta.10 🚧

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

Enquanto ambos os arquivos .md e .mdx são analisados usando MDX, alguns da sintaxe são tratados de forma ligeiramente diferente. Para a análise mais precisa e melhor suporte a editores, recomendamos usar a extensão .mdx para arquivos que contenham sintaxe MDX.

caution

O MDX não é 100% compatível com o CommonMark.

Use the MDX playground to ensure that your syntax is valid MDX.

Tente este bloco aqui:

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!


Você também pode importar seus próprios componentes definidos em outros arquivos ou componentes de terceiros instalados via npm! Confira a documentação MDX para ver quais outras coisas legais que você consegue fazer com o MDX.

caution

Como todos os arquivos doc são analisados usando MDX, qualquer HTML é tratado como JSX. Portanto, se você precisar criar um estilo embutido em um componente, siga o tipo JSX e forneça objetos de estilo. Este comportamento é diferente do Docusaurus 1. Veja também Migrando da v1 para a v2.

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. Para usar o raw-loader, primeiro você precisa instalá-lo em seu projeto:

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

Você também pode passar a propriedade title para o componente CodeBlock a fim de exibi-lo como cabeçalho acima do seu bloco de código:

<CodeBlock className="language-jsx" title="/src/myComponent">
{MyComponentSource}
</CodeBlock>
note

Você deve usar <CodeBlock> em vez do Markdown triple-backtick ```, porque o último enviará qualquer conteúdo como está, mas você deseja JSX para inserir o texto importado aqui.

warning

Este recurso é experimental e pode estar sujeito a alterações importantes da API no futuro.

Importando Markdown

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

Por convenção, usar o _ prefixo de nome de arquivo não criará nenhuma página de documento e significa que o arquivo markdown é um "parcial", a ser importado por outros arquivos.

_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.


Desta forma, você pode reutilizar o conteúdo entre várias páginas e evitar a duplicação de materiais.

caution

Atualmente o conteúdo da tabela não contém as categorias Markdown importadas. 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>

The table of contents for this page, serialized:

[
{
"value": "Usando JSX no Markdown",
"id": "using-jsx-in-markdown",
"children": [],
"level": 2
},
{
"value": "Importando trechos de código",
"id": "importing-code-snippets",
"children": [],
"level": 2
},
{
"value": "Importando Markdown",
"id": "importing-markdown",
"children": [],
"level": 2
},
{
"value": "Available exports",
"id": "available-exports",
"children": [],
"level": 2
}
]

The front matter of this page:

  • id: react
  • title: MDX e 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