Introdução ao MDX!

January 08, 2022

Tempo de leitura: 2 minutos

É bem possível que você já teve contato com o formato Markdown (*.md). Seja quando abriu um Pull Request, durante um chat do Facebook ou escrever um comentário no Reddit.

A filosofia por trás do Markdown é a simplicidade: textos devem ser legíveis sem a necessidade de marcações (tags) que acabam por confundir o leitor (exemplo HTML). Posto de outra forma, um arquivo markdown deve maximizar a separação entre formato e conteúdo. Não obstante, deve haver maneiras de adicionar modificadores de texto como listas, negrito, itálico e etc.

A simplicidade do markdown vem desde a sua especificação em que poucas páginas descrevem as sintaxe da linguagem. E talvez esteja aí umas das principais limitações de se documentar em markdown. Quando a documentação exige componentes mais complexos, como por exemplo um colapse, a versão original do markdown não tem suporte. Por essa razão, existem alguns “sabores” de markdown que propõe alguns elementos sintáticos que aumentam as possibilidades de documentar em determinados contextos. Um exemplo é superset do markdown utilizado pelo Github. Um outro “sabor” que vem ganhando popularidade é o MDX!.

MDX

Em resumo o formato MDX permite que você inclua componentes JSX dentro de um arquivo markdown. MDX funciona com o Gatsby por meio de um plugin gatsby-plugin-mdx. Você pode saber mais sobre o uso do JSX nos documentos do Gatsby: Getting Started with MDX.

Componentes Customizados

Suponha que você tenha escrito um componente Button no seu projeto que esteja localizado em src/components/button. Você pode importar no seu arquivo *.mdx os seus componentes customizado escritos em React.

// Import custom component
import Button from "src/components/button"

<Button color='yellow' marginBottom='25px'>Test</Button>

Com base no código anterior um botão será renderizado na sua página conforme o exemplo a seguir:

Para que seja possível importar seus componentes é necessário utilizar o plugin gatsby-plugin-root-import de modo a disponibilizar o caminho relativo do componente.

• Padrões de Projeto 101 →