Como escrever um artigo em MDX neste blog

Este texto é a minha cola. Quando escrevo pelo celular, é fácil esquecer como se faz um destaque ou onde vai a legenda de uma imagem. Então juntei tudo aqui: cada recurso aparece funcionando e, logo abaixo, o código que o produz.

O que é MDX#

MDX é Markdown que aceita componentes. Na prática, você escreve como sempre escreveu (**negrito**, ## título, listas) e, quando precisa de algo que o Markdown não tem, como uma imagem com legenda, usa uma tag como <Figure />.

O arquivo de cada texto mora em content/blog/ e o nome dele é a URL. Este aqui é como-escrever-um-artigo-em-mdx.mdx, por isso o endereço termina em /blog/como-escrever-um-artigo-em-mdx.

Do celular até o site#

Eu escrevo no Pages CMS, que mostra os arquivos do repositório como um formulário. Cada vez que toco em Salvar, ele faz um commit no GitHub, e a Vercel gera o site de novo. Não existe banco de dados nem painel: o texto é um arquivo, e o histórico dele é o do Git.

Se o seu blog usa outras ferramentas#

A ideia é a mesma em qualquer combinação: o texto é um arquivo no repositório, e cada mudança gera o site de novo. Só os nomes mudam.

Confira se as peças conversam entre si. O Pages CMS, por exemplo, só funciona com repositórios no GitHub; o Decap CMS também aceita GitLab e Bitbucket.

Os campos do formulário#

A parte de cima do arquivo, entre os dois ---, se chama frontmatter. Ela existe em qualquer blog com Markdown. No Pages CMS ela vira o formulário; no arquivo, fica assim:

---
title: Como escrever um artigo em MDX neste blog
date: 2026-10-10
summary: Uma ou duas frases sobre o texto.
tags:
  - MDX
  - Markdown
draft: true
---

Rascunho ou publicado#

Neste blog, um rascunho fica salvo no GitHub, mas não vai para o ar. A contrapartida é que, pelo celular, não dá para ver como ele está ficando: só no computador, com npm run dev.

O básico do Markdown#

Isto aqui é negrito, isto é itálico, isto é riscado e isto é código no meio da frase. Um link para outro site abre uma prévia quando você passa o mouse, como este para o guia de Markdown do GitHub. Um link para dentro do blog é escrito com o caminho, como a busca.

Isto aqui é **negrito**, isto é *itálico*, isto é ~~riscado~~ e isto é
`código no meio da frase`.

[texto do link](https://exemplo.com)
[link interno](/busca)

Listas com marcador:

• uma ideia por item;
• itens curtos leem melhor no celular;
• dá para aninhar:
  • com dois espaços antes do hífen.

E numeradas, quando a ordem importa:

1. Escrever com Rascunho marcado.
2. Revisar no dia seguinte.
3. Desmarcar Rascunho e salvar.

- uma ideia por item
- dá para aninhar:
  - com dois espaços antes do hífen

1. Escrever com Rascunho marcado.
2. Revisar no dia seguinte.

Para atalhos de teclado existe a tag kbd: a busca do blog abre com Ctrl + K.

<kbd>Ctrl</kbd> + <kbd>K</kbd>

Uma linha com três hífens, sozinha, vira um separador como o de cima.

Títulos e o índice#

O título do texto já é o #. Dentro do texto, comece em ## e use ### para as subseções. Com três títulos ou mais, aparece o índice Neste artigo: ao lado do texto na tela grande, e num botão no canto da tela no celular.

## Uma seção
### Uma subseção

Destaques#

Destaques chamam atenção para uma nota, uma dica ou um aviso. O jeito mais simples é a sintaxe do GitHub¹, que é Markdown comum:

> [!NOTE]
> Uma nota.

> [!TIP]
> Uma dica.

> [!WARNING] Um título só seu
> Um aviso, com título próprio na primeira linha.

Os nomes em português também funcionam: [!NOTA], [!DICA] e [!AVISO].

Existe também o componente Callout, que faz exatamente o mesmo:

<Callout type="dica" title="Prefira a sintaxe do GitHub">

O conteúdo, com uma linha em branco antes e depois.

</Callout>

Blocos de código#

Três crases abrem e fecham um bloco. A palavra depois das crases é a linguagem, que define as cores. Cada bloco ganha uma barra com o nome e um botão copiar.

export function soma(a: number, b: number) {
  return a + b;
}

Com title, a barra mostra o nome do arquivo:

export function soma(a: number, b: number) {
  return a + b;
}

Com showLineNumbers, as linhas são numeradas:

export function soma(a: number, b: number) {
  return a + b;
}

export function media(valores: number[]) {
  return valores.reduce(soma, 0) / valores.length;
}

E com bash, o bloco vira um terminal:

npm run dev

```ts title="src/soma.ts" showLineNumbers
export function soma(a: number, b: number) {
  return a + b;
}
```

```bash
npm run dev
```

As cores são aplicadas no build pelo Shiki, com um tema para o claro e outro para o escuro. Nenhum código de realce vai para o navegador de quem lê.

Citações#

Uma citação começa com >. Se a última linha começar com travessão, o botão copiar citação inclui o autor.

Programas devem ser escritos para pessoas lerem e, só incidentalmente, para máquinas executarem.

— Harold Abelson, Structure and Interpretation of Computer Programs

copiar citação

> Programas devem ser escritos para pessoas lerem e, só incidentalmente, para
> máquinas executarem.
>
> — Harold Abelson

O > é Markdown comum. O botão copiar citação é deste blog.

Notas de rodapé#

Uma nota de rodapé guarda um detalhe sem interromper a frase². Tocar no número abre a nota por baixo, sem sair do lugar; com o mouse, basta passar por cima.

Uma frase com nota.[^1]

[^1]: O texto da nota, que pode ficar em qualquer lugar do arquivo.

A sintaxe funciona em quase todo blog com Markdown. Abrir a nota por baixo, sem rolar a página, é coisa deste site; em outros lugares, o número leva até o fim do texto.

Imagens#

Em qualquer Markdown, uma imagem é assim:

![O que a imagem mostra](/caminho/da/imagem.png)

<Figure
  src="/content/blog/meu-texto/diagrama.png"
  alt="O que a imagem mostra, para quem não vê."
  caption="Legenda opcional, que aparece embaixo."
/>

Para duas ou três imagens lado a lado, como as do rascunho e do publicado lá em cima, há a galeria:

<Gallery columns={2}>
  <Figure src="/content/blog/meu-texto/a.png" alt="..." />
  <Figure src="/content/blog/meu-texto/b.png" alt="..." />
</Gallery>

A capa que o blog gera#

Um texto sem Imagem de capa ganha uma capa feita a partir do título, da data, da primeira tag e do tempo de leitura. É a mesma imagem que aparece quando alguém compartilha o link. A deste texto é esta:

Por isso o campo de capa quase sempre fica vazio. Uma imagem ali substitui as duas, a do topo e a de compartilhamento.

O que vem de graça#

Neste blog, nenhum destes precisa de código no texto:

• o tempo de leitura (passe o mouse para ver a que horas você termina);
• o índice, a partir de três títulos;
• os links para resumir o texto com IA, logo abaixo do resumo;
• compartilhar, comentários e textos relacionados no fim;
• a versão em Markdown do texto, para quem prefere a fonte³;
• a entrada no RSS e no sitemap.

Antes de publicar#

1. Releia com Rascunho marcado, de preferência no dia seguinte.
2. Confira se o nome do arquivo ficou sem acento.
3. Veja se as tags já existem em /tags.
4. Desmarque Rascunho e salve.
5. Se o texto tiver links para outros sites, rode npm run links no computador, para as prévias mostrarem título e descrição. Esse comando é deste blog.

npm run links

Pronto. Agora é só escrever.