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

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.

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

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. Abaixo, estamos importando de outro arquivo e inserindo como componente.

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

http://localhost:3000

A documentação é uma das interfaces do seu produto com seus usuários. Um conjunto de documentos bem escrito e bem organizado ajuda os usuários a entender o seu produto rapidamente. Nosso objetivo alinhado aqui é ajudar seus usuários a encontrar e entender as informações de que precisam, o mais rapidamente possível.

O Docusaurus 2 usa ferramentas modernas para ajudá-lo a escrever suas documentações interativas com facilidade. Você pode incorporar componentes React, ou construir blocos de codificação ao vivo, onde seus usuários podem jogar com o código no local. Comece a compartilhar seus momentos de eureka com o código do qual seu público não pode fugir. É talvez a forma mais eficaz de atrair potenciais utilizadores.

Nessa seção, gostaríamos de apresentar-lhe as ferramentas que escolhemos e que acreditamos ajudarão você a construir uma documentação poderosa. Deixe-nos mostrar um exemplo.

Markdown é uma sintaxe que permite escrever conteúdo formatado em uma sintaxe legível.

A sintaxe Markdown padrão é compatível e usamos MDX como o mecanismo de análise, que pode fazer muito mais do que apenas analisar Markdown, como renderizar componentes React dentro de seus documentos.

important

Essa seção presume que você está usando os plugins oficiais de conteúdo do Docusaurus.

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