Este é um guia completo de MDX, que combina o poder do Markdown com componentes React interativos.

MDX permite que você escreva JSX diretamente em seus arquivos Markdown, criando experiências ricas e interativas. Você pode usar todos os recursos tradicionais do Markdown (listas, links, tabelas, código) junto com componentes React customizados.

Este artigo demonstra tanto os recursos clássicos do Markdown quanto as funcionalidades exclusivas do MDX que fazem dele uma ferramenta poderosa para documentação interativa e conteúdo dinâmico.

Texto 1
Texto 2

Links

Arquitetura Gritante

Downloads de Resources

Este post possui resources definidos no frontmatter. Aqui está um exemplo de como fazer download:

📄 A CSV file - Arquivo CSV de exemplo definido nos resources

Estilos

Texto1
Texto 2

Isto é um negritão feito de maçã!

lalala

lalalasdflja.

laslala.

Texto

At quisque litora ullamcorper maecenas ultricies ut dignissim luctus curabitur, cras congue eget primis aliquam fringilla nulla dictum posuere, vestibulum sit magnis nisl praesent eros ipsum nunc. Ligula lacus ipsum orci aenean integer pharetra habitasse interdum, porttitor etiam hac feugiat placerat morbi posuere turpis leo, quam at amet gravida commodo fringilla erat.

Line breaks

Uma linha
Depois da outra

Uma linha
Depois da outra

Uma linha
Depois da outra (juntas)

Hard breaks

Daqui pra baixo, hardbreaks valem sempre.
Como visto aqui.

Admonitions (admoestações)

Imagens

Imagem:

Imagem com texto alternativo:

Seções numeradas

teste

Subseção

assdf

Listas

TODO list

• item 1
• item 2
• item 3

npm install @mdx-js/loader @mdx-js/react

Blocos delimitados

Bloco _delimitado_
com código dentro

meuarquivo.cs

Pessoa x = new() {
    Nome = "Guilherme", // <1>
    Maas = "Maas"       // <2>
};

1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse quis varius velit. Donec dictum consequat nisi, eu tincidunt erat pharetra a. Phasellus id fringilla massa. Pellentesque malesuada volutpat risus, in posuere quam ullamcorper eget. Interdum et malesuada fames ac ante ipsum primis in faucibus. Maecenas sodales dui congue posuere finibus. Aliquam condimentum sapien et porta porttitor. Morbi dui est, sodales a nisi quis, lacinia pellentesque nulla. Aliquam sapien sapien, blandit id dignissim eu, varius aliquam turpis. Sed vitae feugiat nibh, et accumsan risus. Nulla hendrerit in nisl vitae bibendum. Quisque bibendum nisl sed massa pulvinar viverra. Phasellus et dapibus odio. Ut at ultricies arcu.

2. Vivamus et lectus id lacus commodo cursus vitae vitae orci. Donec dapibus porta nunc, at laoreet erat ultrices quis. Pellentesque tincidunt est vel facilisis mattis. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Ut vel augue eros. Nam quis tincidunt leo. Proin placerat commodo mi at aliquet. Nullam vel est nisl. Sed ut dui urna. Vivamus in vehicula urna, sit amet tempor dolor. Mauris luctus vestibulum ipsum vel rutrum.

meuarquivo.js

let x = 10

--attribute sectanchors \
    --attribute figure-caption! \
    --attribute toc-title! \
-   -
+   - | sed -E -e "s/img src=\"([^/]+)\"/img src=\"\/diagram\/\1\"/" // <1>
+
+ mkdir -p static/diagram
+
+ if ls *.svg >/dev/null 2>&1; then
+ mv -f *.svg static/diagram
+ fi
+
+ if ls *.png >/dev/null 2>&1; then
+ mv -f *.png static/diagram
+ fi

1. callout

Admonitions (Avisos)

HTML Direto

Em MDX, você pode usar HTML diretamente quando necessário:

Título com estilo inline

Block metadata

Abaixo do título, vêm metadados (id, quotes, etc).

Gettysburg Address (title)

Four score and seven years ago our fathers brought forth on this continent a new nation…

Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure. …

— Abraham Lincoln, Address delivered at the dedication of the Cemetery at Gettysburg

Quotes

Sobre quotes.

One line quotes

Never do today what you can put off ‘til tomorrow.

Block quotes

Testando diferentes formatos de blockquotes:

Formato original (deve criar múltiplas linhas):

asdjflkajsdfklasflkaj fajsllkf jalkjlksf klasjlkf aldfjkaklsjfd asj alksjdfklajfdkljasklfd

Formato com linhas vazias (deve criar parágrafos separados):

Primeira linha do blockquote

Segunda linha após linha vazia

Terceira linha após linha vazia

Formato contínuo (deve ficar em uma linha):

Texto contínuo sem quebras de linha que deve aparecer como um parágrafo único.

Tabelas

Outra tabela:

Mais outra tabela:

Ainda mais outra tabela, com tamanhos relativos de colunas:

Em MDX, você pode usar HTML dentro das células das tabelas para formatação avançada:

Tabela com JSX:

Em MDX, as tabelas são mais flexíveis pois você pode incluir JSX diretamente nas células.

Em MDX, tabelas seguem a sintaxe padrão do Markdown com GitHub Flavored Markdown:

PERGUNTAS E RESPOSTAS

What is the answer?
This is the answer.

What is the other answer?
This is the other answer.

What is Life?
This is the answer.

What is the other answer?
This is the other answer.

Cross References (xref)

Veja mais em tableas Tabelas.

Recursos Específicos do MDX

O MDX vai além do Markdown tradicional, permitindo componentes React e JSX:

Componentes React (Admonitions)

MDX permite usar componentes React diretamente no Markdown. Os componentes de admonition já são um exemplo disso:

HTML com Estilos Inline

<div style={{ 
  background: 'linear-gradient(45deg, #f0f0f0, #e0e0e0)', 
  padding: '1rem', 
  borderRadius: '8px',
  textAlign: 'center'
}}>
  Div estilizada com JSX!
</div>

Expressões JavaScript Simples

Você pode usar expressões JavaScript básicas:

• Cálculo: 2 + 3 = 5
• Ano atual: 2026
• Texto maiúsculo: MDX É LEGAL

Componentes em Tabelas

Componente Asciinema

O MDX também permite usar componentes customizados mais complexos, como o reprodutor de gravações de terminal Asciinema:

<Asciinema src="/assets/posts/atualizando-basic-computer-games/462009.cast" />

Teste de Tabela

Esta é uma tabela de teste para verificar se o remark-gfm está funcionando:

Componente Code Personalizado

Agora você pode usar o componente <Code> personalizado com syntax highlighting:

Exemplo C#

public class Pessoa 
{
  public string Nome { get; set; }
  public int Idade { get; set; }
  
  public void SaudarPessoa()
  {
      Console.WriteLine($"Olá, eu sou {Nome} e tenho {Idade} anos!");
  }
}

Exemplo JavaScript

const pessoa = {
  nome: 'João',
  idade: 30,
  
  saudar() {
      console.log(`Olá, eu sou ${this.nome} e tenho ${this.idade} anos!`);
  }
};

pessoa.saudar();

Exemplo TypeScript

interface User {
  id: number;
  name: string;
  email: string;
  role: 'admin' | 'user' | 'guest';
}

class UserService {
  private users: User[] = [];
  
  addUser(user: Omit<User, 'id'>): User {
      const newUser: User = {
          ...user,
          id: Date.now()
      };
      
      this.users.push(newUser);
      return newUser;
  }
  
  getUserById(id: number): User | undefined {
      return this.users.find(user => user.id === id);
  }
}

Exemplo Python

class Pessoa:
  def __init__(self, nome: str, idade: int):
      self.nome = nome
      self.idade = idade
  
  def saudar(self) -> None:
      print(f"Olá, eu sou {self.nome} e tenho {self.idade} anos!")

# Uso
pessoa = Pessoa("Maria", 25)
pessoa.saudar()

Exemplo JSON

{
"name": "Blog do Dyego",
"version": "2.0.0",
"description": "Blog técnico migrado de Hugo para NextJS",
"features": {
  "mdx": true,
  "syntax_highlighting": true,
  "dark_mode": true,
  "search": true
},
"dependencies": {
  "next": "15.3.4",
  "react": "19.0.0",
  "react-syntax-highlighter": "^15.5.0"
}
}

Embedding de Tweets

O MDX também permite embedding de tweets do X (antigo Twitter) usando o componente <Tweet>:

Exemplo de Tweet Embedded