MDX no Astro: o markdown que vira componente (e o que isso muda)

Este post é, ao mesmo tempo, sobre MDX e escrito em MDX. Todos os componentes que você vê abaixo — gráfico animado, contador interativo, abas, timeline, callouts coloridos — são componentes Astro reais importados no topo do arquivo .mdx e usados inline no meio do markdown. Continua sendo um post estático, sem framework client-side, com HTML pré-renderizado em build-time.

O conceito em uma frase

MDX é markdown + JSX. Você escreve # título e **negrito** como sempre, mas pode intercalar <Componente prop="x" /> em qualquer lugar — e o componente é renderizado de verdade no HTML final.

1. Callouts — destacando o que importa

Componentes recebem props como em React/Vue:

<Callout type="warning" title="Cuidado">
Não rode `rm -rf` no diretório errado.
</Callout>

E o resultado:

2. Pull quotes — citações de impacto

Em um post técnico, citar fontes ou ressaltar uma frase-chave melhora muito o ritmo. Em vez do > padrão do Markdown:

3. Tabelas — Markdown nativo continua funcionando

Tabelas comuns continuam suportadas:

4. Gráficos animados — sem biblioteca de chart

Para visualizações simples, não precisa de Recharts, D3 ou Chart.js. Animação CSS pura funciona:

Cada barra anima do zero até seu valor com cubic-bezier(.4, 0, .2, 1), com delay incremental — o tipo de polimento que normalmente exige uma lib de 50KB.

5. Componente interativo — o caso real de hidratação

Aqui o ponto fica interessante. O componente abaixo tem estado real (count) e responde a clicks. Mas observe: ele usa <script> inline, não um framework. É vanilla JS rodando no cliente, e o resto da página continua HTML estático.

Se preferir React/Vue/Svelte para componentes mais complexos, basta:

---
import Chart from '../components/Chart.jsx';
---
<Chart client:visible dados={[1, 2, 3]} />

A diretiva client:visible carrega o JS só quando o componente entra no viewport — o resto da página nunca paga esse custo.

6. Tabs — comparando alternativas no mesmo lugar

Para mostrar a mesma ideia em linguagens diferentes:

def saudacao(nome: str) -> str:
    return f"Olá, {nome}!"

func saudacao(nome string) string {
    return fmt.Sprintf("Olá, %s!", nome)
}

fn saudacao(nome: &str) -> String {
    format!("Olá, {}!", nome)
}

const saudacao = (nome: string) => `Olá, ${nome}!`;

Útil em tutoriais multi-linguagem ou comparações de stack.

7. Stats animados — números que contam ao entrar no viewport

Usando IntersectionObserver, os números animam de 0 até o valor real quando o usuário rola até eles:

8. Timeline — narrativas com sequência

Para histórias técnicas (changelogs, incident timelines, roadmap):

1. 2016

   Snowpack lançado

   Antecessor do que viraria Astro — bundle-less dev server.

2. 2021

   Astro 0.x

   Primeiro release público com islands architecture.

3. 2023

   Astro 3.0

   View Transitions API integrada, build 50% mais rápida.

4. 2025

   Astro 5.0

   Content Layer API, Server Islands, 12 minor releases no ano.

5. 2026

   Padrão de fato

   Usado pela documentação da OpenAI, Cloudflare e mais 40+ empresas grandes.

9. Comparativos lado a lado

Antes/depois, do jeito errado vs jeito certo:

10. Imagens com legenda apropriada

Imagens Markdown padrão (![alt](url)) viram só <img> sem semântica. Para fotos com crédito e legenda explicativa:

O custo real de tudo isso

Em um framework SPA (Next.js, Nuxt), essa mesma página enviaria entre 80-200 KB de runtime do framework, antes do código do post. Aqui o JS só existe onde precisa de fato existir.

Quando não usar MDX

Para o resto — posts técnicos, tutoriais com código, análises com gráficos, comparações arquiteturais — MDX é o que separa um blog texto de uma página real de produto.

TL;DR

MDX no Astro é a feature que justifica escolher Astro como plataforma de blog técnico em 2026. Markdown + JSX + hidratação seletiva + zero opinião sobre framework. O que mais um time pode pedir?

Próximos passos: copia esses 9 componentes (src/components/), cria seu primeiro .mdx, e converte um post existente para usar 2-3 callouts. O ganho de leitura é imediato.