MDX e React

Usando JSX no Markdown

O Docusaurus tem suporte embutido para MDX, que permite que você escreva JSX dentro de seus arquivos Markdown e processá-los como componentes React.

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 o MDX playground para garantir que a sua sintaxe é um MDX válido.

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

npm install --save raw-loader

Yarn

yarn add 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).