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

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

Tour prático: como markdown + componentes Astro transformam um blog técnico em algo interativo, animado e ainda assim 100% estático.

O Autor Descontente · 29 de maio de 2026 · 9 min de leitura

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:

Astro é uma ilha em meio ao oceano de frameworks JavaScript. Você escolhe onde a hidratação acontece — não o framework.

— Fred Schott , Astro Docs, 2024

3. Tabelas — Markdown nativo continua funcionando

Tabelas comuns continuam suportadas:

FrameworkStackBuild inicialJS no cliente
AstroNode + TS~52 s0 KB ⭐
HugoGo (binário)~30 s0 KB
DocusaurusReact + Webpack~3 min~280 KB
JekyllRuby~2 min0 KB
VitePressVue + Vite~45 sVue runtime

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:

Custo mensal estimado por framework no AWS
Astro
2 USD
Hugo
1 USD
Eleventy
2 USD
Jekyll
3 USD
Hexo
3 USD
VitePress
4 USD
Docusaurus
8 USD

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.

⚡ 0 vezes que você apertou esse botão

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:

⚡
0
Build CI
segundos
📦
0
Página home
KB total
🚀
0
Lighthouse score
Performance
💸
0
AWS / mês
em USD

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:

✕ Sem MDX (markdown puro)

Aspas como ferramenta primária de destaque visual. Tabelas para tudo. Imagens com link para um chart externo do Google Sheets. Nenhuma interatividade.

✓ Com MDX

Callouts coloridos. Gráficos inline animados. Tabs comparativos. Contadores e demos ao vivo. Tudo no mesmo .mdx que continua versionado no Git como texto.

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:

Diagrama de islands architecture
Arquitetura de Islands — só os componentes marcados hidratam, o resto fica HTML estático. — Astro Docs

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.

← voltar para todos os posts