Astro Markdown e MDX avançados: 7 técnicas para um blog mais profissional

Você acabou de criar um blog com Astro e começou a escrever seu primeiro artigo técnico. Quer destacar uma linha específica do código? Não consegue. Quer adicionar uma caixa de aviso recolhível para chamar a atenção do leitor? Também não. Quer incluir uma fórmula matemática na explicação de um algoritmo? Não sabe nem por onde começar.

Eu já passei por esse desconforto. Depois de escrever alguns artigos em Markdown puro, percebi que as possibilidades de expressão eram limitadas demais. Em outros blogs técnicos, os blocos de código destacavam pontos importantes, comparavam o antes e o depois de uma alteração e até incorporavam componentes interativos. No meu, eu só conseguia colar código sem nenhum recurso adicional.

Por sorte, o Astro oferece o MDX, uma espécie de “Markdown aprimorado”. Em termos simples, o MDX permite usar componentes e escrever JSX dentro do artigo, ampliando bastante o que você pode fazer.

Neste artigo, compartilho sete usos avançados de Markdown e MDX no Astro. Eles vão da configuração básica do ambiente ao destaque de código, aos componentes personalizados, às fórmulas matemáticas e aos diagramas. Cada técnica inclui o código completo e as etapas de configuração. O objetivo é levar seu blog técnico de algo que apenas funciona a uma experiência realmente profissional.

Parte 1: a base — do Markdown ao MDX

Por que usar MDX?

A diferença entre Markdown e MDX se parece com a diferença entre uma bicicleta e uma bicicleta elétrica: as duas levam você ao destino, mas a experiência é bem diferente.

O Markdown puro se limita a conteúdo estático, como texto, blocos de código e imagens. Quer incluir uma caixa informativa? Precisa escrever HTML manualmente. Quer incorporar um componente interativo ao artigo? Na prática, não dá.

Com MDX é diferente. Ele combina Markdown e JSX, então você pode:

• Importar e usar componentes: importe diretamente em um arquivo .mdx qualquer componente Astro, React ou Vue
• Escrever expressões JSX: insira uma variável no artigo com {variable} ou até escreva loops e condições
• Personalizar estilos de elementos: substitua o <h1> padrão por um componente estilizado por você

Veja um exemplo concreto. Para adicionar uma caixa de aviso em Markdown puro, você teria de escrever:

<div class="warning">
  <p>Atenção: esta operação excluirá todos os dados!</p>
</div>

Com MDX, basta fazer isto:

import Alert from '@/components/Alert.astro';

<Alert type="warning">
  Atenção: esta operação excluirá todos os dados!
</Alert>

Percebeu a diferença? Com MDX, criar um artigo se parece mais com montar blocos do que com escrever HTML manualmente.

Configure o ambiente MDX em 5 minutos

Configurar MDX é simples e leva apenas três etapas.

Etapa 1: instale a integração

Abra o terminal e execute o comando dentro do projeto Astro:

npx astro add mdx

O Astro CLI instalará @astrojs/mdx e atualizará o arquivo de configuração automaticamente. O comando fará algumas perguntas, como se você quer atualizar a configuração e instalar as dependências. Responda Yes a todas.

Etapa 2: confira a configuração

Depois da instalação, abra astro.config.mjs. O arquivo deve conter algo assim:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
});

Se o trecho não tiver sido incluído automaticamente, adicione-o manualmente.

Etapa 3: teste se o MDX funciona

Crie um arquivo test.mdx em src/pages/ ou src/content/:

---

title: Teste de MDX

---

# Este é um teste de MDX

Texto Markdown comum.

export const greeting = "Olá";

Agora você pode usar uma variável: {greeting}!

<div style="padding: 1rem; background: #f0f0f0;">
  Este é um elemento JSX
</div>

Execute npm run dev e abra a página correspondente. Se a variável e o elemento JSX aparecerem corretamente, o MDX está configurado.

Sobre a convivência entre arquivos .md e .mdx

Depois que você instala a integração do MDX, os arquivos .md continuam funcionando normalmente. O Astro escolhe o processamento de acordo com a extensão:

• Arquivos .md: processados como Markdown padrão
• Arquivos .mdx: processados como MDX, com suporte a componentes e JSX

Minha sugestão é usar .md em artigos comuns e .mdx quando você precisar de componentes. Nem todo artigo precisa dos recursos do MDX.

Parte 2: técnicas avançadas de destaque de código

Configure o tema de destaque de código com Shiki

O Astro usa o Shiki por padrão para destacar código, e a configuração inicial já funciona muito bem. O tema padrão é github-dark, mas talvez você queira algo mais alinhado ao visual do seu blog.

Shiki ou Prism: qual escolher?

Sinceramente, recomendo o Shiki. Ele é a solução padrão do Astro, aceita mais de cem linguagens e temas e renderiza no servidor, sem carregar JavaScript adicional. O Prism também é bom, mas exige um arquivo CSS e sua configuração dá um pouco mais de trabalho.

Troque o tema integrado

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Abra astro.config.mjs e adicione shikiConfig à configuração de markdown:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'dracula', // Opções: github-dark, nord, monokai, dracula etc.
    },
  },
});

O Shiki oferece muitos temas. Estes são alguns dos que eu mais uso:

• github-dark / github-light — estilo do GitHub
• dracula — combinação clássica de roxo e preto
• nord — paleta fria de inspiração nórdica
• one-dark-pro — tema escuro padrão do VS Code

Você pode escolher um tema na galeria de temas do Shiki.

Use temas diferentes nos modos claro e escuro

Se o blog permite alternar entre os modos claro e escuro, o Shiki aceita dois temas:

markdown: {
  shikiConfig: {
    themes: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
},

Com essa configuração, o Shiki aplica o tema correto de acordo com prefers-color-scheme no CSS ou com a lógica personalizada de troca de tema do seu site.

Destaque linhas específicas e anotações no código

Ao escrever um tutorial, é comum precisar indicar que uma linha merece atenção ou mostrar exatamente o que mudou. Os Shiki Transformers resolvem esses dois casos.

Destaque linhas importantes

Primeiro, instale os transformers do Shiki:

npm install shiki

Depois, ative transformerNotationHighlight na configuração:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import { transformerNotationHighlight } from '@shikijs/transformers';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
      transformers: [transformerNotationHighlight()],
    },
  },
});

Agora você pode usar o comentário // [!code highlight] dentro do bloco de código para marcar a linha que deve ser destacada:

```javascript
function hello() {
  console.log('Esta linha é comum');
  console.log('Esta linha ficará destacada'); // [!code highlight]
}
```

Mostre alterações no estilo diff

Para comparar o código antes e depois de uma mudança, use transformerNotationDiff:

import { transformerNotationDiff, transformerNotationHighlight } from '@shikijs/transformers';

markdown: {
  shikiConfig: {
    theme: 'github-dark',
    transformers: [
      transformerNotationHighlight(),
      transformerNotationDiff(),
    ],
  },
},

Uso:

```javascript
function calculate(a, b) {
  return a + b; // [!code --]
  return a * b; // [!code ++]
}
```

A linha marcada com -- aparece em vermelho, indicando remoção, e a linha com ++ aparece em verde, indicando adição. Esse recurso é muito útil em tutoriais de programação.

Coloque o foco em uma parte do código

Outro recurso é transformerNotationFocus, que deixa o restante do código esmaecido e mantém em evidência apenas o trecho importante:

import { transformerNotationFocus } from '@shikijs/transformers';

// Adicione ao array transformers
transformers: [
  transformerNotationFocus(),
],

Marque a linha com // [!code focus]:

```javascript
function process() {
  console.log('Esta linha ficará esmaecida');
  console.log('Esta linha terá aparência normal'); // [!code focus]
  console.log('Esta linha também ficará esmaecida');
}
```

Migre para o Expressive Code, se precisar

Se os recursos do Shiki ainda não forem suficientes, experimente o Expressive Code. Essa solução criada pela comunidade aprimora a apresentação dos blocos de código e oferece mais recursos prontos para uso:

• Título do bloco de código
• Botão para copiar com um clique
• Números de linha
• Estilo de janela do terminal
• Comparação de código lado a lado

A instalação é simples

npx astro add astro-expressive-code

O Astro CLI configura tudo automaticamente. Depois da instalação, os blocos de código passam a oferecer esses recursos sem nenhuma configuração adicional.

Quando usar Expressive Code?

No começo, eu usava apenas o Shiki padrão. Quando percebi que os leitores copiavam código com frequência, migrei para o Expressive Code. Se o seu blog é voltado principalmente a tutoriais e exemplos de programação, ele melhora bastante a experiência do leitor.

Se você publica código apenas de vez em quando, Shiki com Transformers já resolve o problema, sem acrescentar outra dependência ao projeto.

Parte 3: incorpore componentes personalizados

Importe e use componentes no MDX

O principal recurso do MDX é permitir o uso direto de componentes no artigo. Eu o uso com frequência para criar caixas informativas, comparações de código e áreas recolhíveis.

Crie um componente de aviso

Primeiro, crie Alert.astro no diretório src/components/:

---

interface Props {
  type?: 'info' | 'warning' | 'error';
}

const { type = 'info' } = Astro.props;

const styles = {
  info: 'bg-blue-50 border-blue-200 text-blue-800',
  warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
  error: 'bg-red-50 border-red-200 text-red-800',
};

---

<div class={`border-l-4 p-4 ${styles[type]}`}>
  <slot />
</div>

Use o componente em um artigo MDX

Importe e use o componente dentro do arquivo .mdx:

---

title: Meu artigo técnico

---

import Alert from '@/components/Alert.astro';

# Título do artigo

Este é o conteúdo comum do artigo.

<Alert type="warning">
  Atenção: faça backup dos dados antes de executar este comando!
</Alert>

<Alert type="info">
  Dica: você também pode usar **sintaxe Markdown** dentro do componente.
</Alert>

Percebeu? Dentro do componente <Alert>, você continua usando sintaxe Markdown, como negrito e links, e o MDX cuida do processamento.

Use componentes React ou Vue

O MDX não se limita a componentes Astro. Você também pode usar componentes React, Vue e de outros frameworks. Lembre-se, porém, de adicionar uma diretiva client::

import Counter from '@/components/Counter.tsx';

<Counter client:load initialCount={0} />

client:load indica que o componente será executado no cliente assim que a página carregar. Sem a diretiva, ele será renderizado apenas no servidor e a interatividade não funcionará.

Sugestão para organizar os componentes

Eu costumo manter os componentes usados nos artigos dentro de src/components/mdx/, o que facilita a organização:

src/
├── components/
│   ├── mdx/
│   │   ├── Alert.astro
│   │   ├── CodeCompare.astro
│   │   ├── Callout.astro
│   │   └── Tabs.astro
│   └── ...outros componentes

Mapeie a sintaxe Markdown para componentes personalizados

Esse recurso parece um pouco com “magia”: você pode substituir elementos Markdown padrão, como h1, a e img, pelos seus próprios componentes.

Por que fazer isso?

Imagine que você queira adicionar um ícone de âncora a todos os títulos ou incluir automaticamente o símbolo ”↗” nos links externos. Fazer isso manualmente em cada ocorrência seria trabalhoso. Com o mapeamento de componentes, você escreve Markdown padrão e o estilo é aplicado automaticamente.

Na prática: um componente de título personalizado

Primeiro, crie CustomHeading.astro:

---

interface Props {
  level: 1 | 2 | 3 | 4 | 5 | 6;
  id?: string;
}

const { level, id } = Astro.props;
const Tag = `h${level}` as any;

---

<Tag id={id} class="group relative">
  <slot />
  {id && (
    <a href={`#${id}`} class="ml-2 opacity-0 group-hover:opacity-100 transition-opacity">
      #
    </a>
  )}
</Tag>

Use o mapeamento no MDX

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Exporte um objeto components no arquivo .mdx:

---

title: Título do artigo

---

import CustomHeading from '@/components/CustomHeading.astro';

export const components = {
  h2: (props) => <CustomHeading level={2} {...props} />,
  h3: (props) => <CustomHeading level={3} {...props} />,
};

## Este é um título de nível 2

Quando o cursor passa sobre o título, aparece um link de âncora #.

### Este é um título de nível 3

Todos os elementos h2 e h3 recebem automaticamente o estilo personalizado.

Na prática: adicione um ícone aos links externos

Crie ExternalLink.astro:

---

interface Props {
  href?: string;
}

const { href } = Astro.props;
const isExternal = href?.startsWith('http');

---

<a href={href} target={isExternal ? '_blank' : undefined} rel={isExternal ? 'noopener noreferrer' : undefined}>
  <slot />
  {isExternal && <span class="ml-1 text-xs">↗</span>}
</a>

Use o mapeamento:

import ExternalLink from '@/components/ExternalLink.astro';

export const components = {
  a: ExternalLink,
};

[Este é um link interno](/about)
[Este é um link externo](https://example.com) ← recebe automaticamente o ícone ↗

Configure um mapeamento global, se necessário

Se quiser aplicar o mesmo mapeamento a todos os arquivos MDX, você pode configurá-lo em astro.config.mjs. Isso exige um plugin MDX personalizado e é um pouco mais complexo. Na maioria dos casos, prefiro configurar o mapeamento em cada arquivo.

Parte 4: integre fórmulas matemáticas e diagramas

Exiba fórmulas matemáticas com KaTeX

Se você escreve sobre algoritmos, matemática ou ciência de dados, provavelmente precisa exibir fórmulas. KaTeX é uma ótima escolha: ele é muito mais rápido que MathJax e oferece renderização no servidor.

Instale o KaTeX

Você precisa instalar três pacotes:

npm install remark-math rehype-katex katex

• remark-math: interpreta a sintaxe LaTeX
• rehype-katex: renderiza as fórmulas como HTML
• katex: biblioteca principal do KaTeX

Configure o Astro

Abra astro.config.mjs e adicione os dois plugins:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

Importe os estilos do KaTeX

Essa etapa é importante, pois as fórmulas não serão exibidas corretamente sem os estilos. Adicione o trecho abaixo ao <head> do layout, como src/layouts/MarkdownLayout.astro:

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css"
  crossorigin="anonymous"
/>

Use fórmulas nos artigos

Depois da configuração, você pode escrever fórmulas em Markdown ou MDX.

Fórmula inline, delimitada por um único $:

Equação de equivalência massa-energia: $E = mc^2$

Solução de uma equação quadrática: $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$

Fórmula em bloco, delimitada por $$:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

Problema comum: a fórmula não aparece

Se a fórmula não aparecer ou o estilo estiver incorreto, confira estes pontos:

1. O CSS do KaTeX foi importado corretamente? Confira a aba Network no DevTools.
2. A versão de rehype-katex é compatível? Experimente a versão 6.x.
3. A sintaxe da fórmula está correta? Consulte a lista de recursos compatíveis com KaTeX.

Integre o Mermaid para criar diagramas de fluxo e outros gráficos

O Mermaid permite criar diagramas de fluxo, diagramas de sequência, gráficos de Gantt e outras visualizações com código. Ele funciona especialmente bem em documentação técnica.

Compare três formas de integração

A comunidade oferece algumas formas de integrar Mermaid. Estas são as diferenças principais:

Recomendo rehype-mermaid. Ele renderiza no servidor, é adequado para SEO e gera SVG estático.

Instale rehype-mermaid

npm install rehype-mermaid

Faça a configuração

Adicione o plugin em astro.config.mjs:

import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import rehypeMermaid from 'rehype-mermaid';

export default defineConfig({
  integrations: [mdx()],
  markdown: {
    rehypePlugins: [
      [rehypeMermaid, { strategy: 'img-svg' }]
    ],
  },
});

strategy: 'img-svg' gera uma imagem SVG e costuma ser a opção mais estável.

Desenhe diagramas no artigo

Basta usar um bloco de código mermaid.

Exemplo de diagrama de fluxo:

```mermaid
graph TD
    A[Início] --> B{MDX está instalado?}
    B -->|Sim| C[Configurar destaque de código]
    B -->|Não| D[Instalar MDX]
    D --> C
    C --> E[Concluído]
```

Exemplo de diagrama de sequência:

```mermaid
sequenceDiagram
    Usuário->>Navegador: Acessa a página
    Navegador->>Servidor: Solicita o HTML
    Servidor->>Navegador: Retorna a página renderizada
    Navegador->>Usuário: Exibe o conteúdo
```

Geração durante o build

Ao executar npm run build, o Mermaid gera os diagramas em SVG durante o build. A página final contém imagens estáticas, carrega rápido e não precisa de JavaScript no cliente.

Pontos de atenção

Se o build mostrar o erro “Puppeteer não encontrado”, talvez seja preciso fazer uma configuração adicional. Experimente instalar o Playwright:

npm install -D playwright

Outra opção é usar astro-diagram, que já inclui um ambiente de navegador.

Parte 5: técnicas avançadas e boas práticas

Otimize MDX com Content Collections

Se você gerencia os artigos do blog com Content Collections do Astro, uma opção que recomendo, os arquivos MDX ganham melhor suporte de tipos e uma experiência de desenvolvimento mais agradável.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

O que são Content Collections?

Em termos simples, você coloca os artigos no diretório src/content/, e o Astro identifica e valida automaticamente o frontmatter, além de oferecer uma API com tipagem para ler o conteúdo.

Configure Content Collections

Defina a coleção em src/content/config.ts:

import { defineCollection, z } from 'astro:content';

const blog = defineCollection({
  type: 'content', // Indica um arquivo de conteúdo em Markdown ou MDX
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.date(),
    tags: z.array(z.string()).optional(),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

Use em MDX

O frontmatter do arquivo MDX será validado automaticamente:

---

title: Tutorial avançado de Astro MDX
description: Aprenda recursos avançados do MDX
pubDate: 2025-12-02
tags: [Astro, MDX, Tutorial]

---

import Alert from '@/components/Alert.astro';

# {frontmatter.title}

<Alert type="info">
  Data de publicação: {frontmatter.pubDate.toLocaleDateString()}
</Alert>

Gere o sumário automaticamente

Content Collections oferece o método getHeadings(), que retorna todos os títulos do artigo e pode ser usado para criar um sumário:

---

import { getEntry } from 'astro:content';

const entry = await getEntry('blog', 'my-mdx-article');
const { Content, headings } = await entry.render();

---

<aside>
  <h2>Sumário</h2>
  <ul>
    {headings.map(h => (
      <li style={`margin-left: ${(h.depth - 1) * 1}rem`}>
        <a href={`#${h.slug}`}>{h.text}</a>
      </li>
    ))}
  </ul>
</aside>

<article>
  <Content />
</article>

Esse recurso é muito útil em textos longos, pois permite que o leitor vá rapidamente à seção que procura.

Otimização de desempenho e armadilhas comuns

MDX é muito versátil, mas pode deixar o site lento quando usado sem cuidado. Estes são alguns pontos importantes.

Evite usar componentes de cliente em excesso

Você pode usar componentes React e Vue no MDX, mas precisa adicionar uma diretiva client:*. Sem ela, o componente será renderizado apenas no servidor e não terá interatividade. Por outro lado, usar client:load em excesso envia muito JavaScript e aumenta o tempo de carregamento.

Minha recomendação:

• Use componentes Astro para conteúdo estático, como Alert e Callout
• Para conteúdo interativo, prefira client:visible, que carrega o componente quando ele fica visível, ou client:idle, que o carrega quando o navegador está ocioso
• Não use client:load sem necessidade

Otimize as imagens

Ao inserir uma imagem em MDX, evite usar <img> diretamente. Prefira o componente Image do Astro:

---

title: Meu artigo

---

import { Image } from 'astro:assets';
import cover from './cover.jpg';

<Image src={cover} alt="Imagem de capa" width={800} height={600} />

O Astro otimiza a imagem automaticamente, incluindo compactação, geração de WebP e carregamento lazy, o que melhora bastante o desempenho.

Use a opção optimize do MDX

Se o site tem muitos arquivos MDX e o build está lento, experimente ativar optimize:

export default defineConfig({
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});

Essa opção usa um plugin rehype interno para otimizar a saída do MDX e acelerar o build. Como ela pode alterar a estrutura do HTML gerado, faça testes antes de adotá-la.

Erros comuns e soluções

Conclusão

Depois de todas essas configurações, estes são os pontos principais.

Revisão rápida das sete técnicas:

1. Configure o ambiente MDX — comece em cinco minutos com um único comando
2. Troque o tema de destaque de código — use o Shiki para combinar o código com o estilo do blog
3. Destaque e anote o código — use Transformers para marcar pontos importantes e mostrar alterações
4. Incorpore componentes personalizados — deixe o artigo mais claro, de caixas Alert a demos interativas
5. Mapeie elementos Markdown — personalize em lote o estilo padrão de títulos, links e outros elementos
6. Exiba fórmulas matemáticas — use KaTeX para apresentar algoritmos com mais clareza
7. Desenhe diagramas de fluxo — escreva os diagramas em Mermaid e renderize-os no servidor

Sugestão de sequência de aprendizado:

Você não precisa aprender todos os recursos de uma vez. Minha sugestão é seguir esta ordem:

• Primeiro passo: configure o ambiente MDX e tente importar um componente simples
• Segundo passo: configure o destaque de código quando o conteúdo do blog exigir muitos exemplos
• Terceiro passo: se você escreve sobre algoritmos ou arquitetura, adicione KaTeX e Mermaid
• Quarto passo: quando estiver mais familiarizado, experimente recursos como o mapeamento de componentes

Checklist:

Depois da configuração, confira se estes recursos funcionam:

• Os arquivos MDX são renderizados corretamente
• Os blocos de código têm o destaque correto
• Os componentes personalizados aparecem
• As fórmulas matemáticas são renderizadas corretamente, se você as configurou
• Os diagramas Mermaid são gerados, se você os configurou
• O tempo de build é aceitável

Próximos passos:

• Explore Astro Integrations para encontrar outros plugins interessantes
• Confira as bibliotecas de componentes MDX criadas pela comunidade
• Experimente usar View Transitions do Astro para adicionar transições suaves entre as páginas do blog

Escolha o recurso que mais chamou sua atenção e experimente aplicá-lo ao blog. Se encontrar algum problema durante a configuração, consulte a documentação oficial ou a comunidade: na maioria dos casos, a solução já está bem documentada.

Por fim, o conteúdo continua sendo a parte mais importante de um blog técnico. Essas ferramentas ajudam a tornar sua explicação mais clara e profissional, mas são suas ideias e sua experiência que realmente atraem os leitores. Espero que seu blog com Astro fique cada vez melhor.