Markdown, MDX ou CMS headless: como escolher

Todo site de conteúdo precisa responder a uma pergunta antes de crescer: onde o texto vai morar e quem vai editá-lo? As respostas mais comuns hoje são três: arquivos Markdown, arquivos MDX ou um CMS headless.

Não existe vencedora universal. Cada opção troca simplicidade por poder, ou autonomia da equipe editorial por mais peças para manter. Este texto compara as três com base na documentação oficial de cada tecnologia e do Astro, consultada em 8 de outubro de 2026.

Markdown: texto simples em arquivos

O Markdown é um formato de texto com marcações leves. Um # no começo da linha vira título, asteriscos viram ênfase, um traço vira item de lista. O arquivo continua legível mesmo sem ser convertido em página.

Como houve muitas variações ao longo dos anos, surgiu uma especificação comum, a CommonMark, cuja versão mais recente listada é a 0.31.2, de janeiro de 2024. Muitas ferramentas também adotam a variante do GitHub, a GFM (GitHub Flavored Markdown).

O Astro, por exemplo, lê Markdown sem instalar nada. A página Markdown in Astro informa que o suporte é nativo, que a GFM vem ligada por padrão e que é possível acrescentar plugins para transformar o texto. Cada arquivo pode ter um frontmatter, um bloco no topo com dados como título, data e autor.

Pontos fortes:

• Portabilidade. É texto puro. Muda de ferramenta, de framework ou de hospedagem sem conversão complicada.
• Versionamento. Os arquivos ficam no repositório Git, com histórico de cada alteração e revisão por pull request.
• Pouca superfície de erro. Não há código a executar dentro do texto.

Limites:

• Quem escreve precisa lidar com arquivos. Para jornalistas ou equipes de marketing sem familiaridade com Git, isso é uma barreira real.
• Pouca expressividade. Um gráfico interativo ou um bloco de aviso personalizado não cabem no Markdown puro. É preciso resolver no modelo da página ou com convenções.

MDX: Markdown com componentes

O MDX é, nas palavras da documentação oficial, “um formato que combina Markdown com JSX”. O JSX é a sintaxe usada em React e outras bibliotecas para escrever componentes de interface com aparência de HTML. No MDX, você pode importar um componente e colocá-lo no meio do texto, além de usar expressões JavaScript entre chaves.

No Astro, o MDX não vem embutido. Ele exige a integração @astrojs/mdx. Com ela, um arquivo .mdx pode importar componentes do Astro e de outras bibliotecas e exportar variáveis.

O ganho é claro: um artigo pode ter uma calculadora, um gráfico ou um bloco de alerta padronizado no meio do texto, sem gambiarras.

O custo aparece em três frentes.

Sintaxe menos tolerante. A mesma página lembra que o Markdown “perdoa” erros, enquanto o JavaScript quebra com um erro de digitação. O MDX também tem diferenças: código indentado não funciona, HTML puro é substituído por JSX, e os caracteres < e { precisam ser escapados quando aparecem no texto. Um sinal de menor solto pode derrubar o build.

Segurança. O guia Getting started do MDX é direto. Ele diz que o MDX é uma linguagem compilada para JavaScript e que, por isso, é seguro se você confia nos autores e inseguro se não confia. A recomendação literal é não deixar “pessoas aleatórias da internet” escreverem MDX. Na prática, comentários de leitores ou textos de colaboradores externos não devem virar MDX sem controle.

Acoplamento. Um artigo em MDX depende dos componentes que importa. Se o componente mudar de nome ou o site mudar de framework, o texto precisa ser revisto. O conteúdo deixa de ser só conteúdo.

CMS headless: conteúdo em um serviço à parte

Um CMS (sistema de gerenciamento de conteúdo) é o software em que a equipe escreve, revisa e organiza o conteúdo. Um CMS headless (“sem cabeça”) faz só essa parte e não gera as páginas. A documentação do Astro sobre CMS explica que, como o Astro cuida da apresentação, o indicado é um CMS headless: ele guarda o conteúdo, e o site busca esses dados para montar as páginas, seja por uma integração pronta, seja pela biblioteca do próprio CMS.

Segundo a mesma página, um CMS costuma oferecer editor visual, tipos de conteúdo padronizados e ferramentas de colaboração. Ele funciona bem para conteúdo estruturado, como posts com editor de texto rico ou fichas de produto com campos obrigatórios.

Há dois grandes modelos:

• CMS por API. O conteúdo fica no banco de dados do serviço, e o site o busca pela internet.
• CMS baseado em Git. O editor visual grava arquivos no próprio repositório. É o caso do Decap CMS, que se descreve como um aplicativo React de código aberto, sob licença MIT, que envolve o fluxo do Git. Quando a pessoa salva no editor, a mudança vira um commit no repositório, sem que ela precise aprender Git.

O modelo baseado em Git é um meio-termo: a equipe ganha uma interface visual, e o conteúdo continua em arquivos, muitas vezes Markdown.

O custo do CMS headless:

• Mais uma peça. Há uma conta, um serviço, permissões e, em muitos casos, uma assinatura para manter. Se o serviço sair do ar ou mudar de preço, o site sente.
• Integração. O site precisa de código para buscar e validar os dados. No Astro, isso é feito com loaders nas coleções de conteúdo, que aceitam dados remotos, como os de um CMS.
• Novo build a cada mudança, em site estático. Se as páginas são geradas no build, uma correção no CMS só aparece depois de um novo build. A mesma documentação descreve as coleções “ao vivo”, que buscam dados a cada requisição, mas elas não aceitam MDX.

Comparação lado a lado

Critério	Markdown	MDX	CMS headless
Quem escreve com conforto	Pessoas técnicas ou habituadas a arquivos	Pessoas técnicas	Qualquer pessoa com acesso ao editor
Onde o conteúdo fica	Repositório Git	Repositório Git	Serviço do CMS (ou Git, nos CMS baseados em Git)
Componentes no meio do texto	Não	Sim	Depende do CMS e da integração
Risco de segurança no conteúdo	Baixo	Alto se autores não forem confiáveis	Depende do controle de acesso do CMS
Portabilidade	Alta	Média (depende dos componentes)	Depende da exportação do serviço
Peças extras para manter	Nenhuma	Integração MDX	Serviço, integração e gatilho de build

As células de risco e portabilidade são avaliação da redação, a partir das características descritas nas fontes, não medições.

Como decidir

Algumas perguntas ajudam a escolher.

Quem vai escrever? Se a equipe é técnica e pequena, Markdown no repositório costuma bastar. Se há editores sem familiaridade com Git, um CMS, por API ou baseado em Git, tende a evitar gargalos.

O texto precisa de componentes? Se poucos artigos precisam de algo interativo, dá para resolver no modelo da página, com campos no frontmatter. Se muitos precisam, o MDX passa a compensar, desde que os autores sejam de confiança.

Quanto o conteúdo muda? Em site estático, cada alteração exige build. Se as mudanças são diárias e feitas por várias pessoas, planeje como o build será disparado.

Quanto você quer depender de terceiros? Arquivos no repositório não dependem de nenhum serviço externo para existir. Um CMS por API, sim.

As opções também se combinam. É comum ter Markdown para a maior parte dos textos, MDX para poucas páginas especiais e um CMS baseado em Git como interface para quem não programa.

Caso documentado: o site do Token & Tech

O site do Token & Tech usa a primeira opção, e isso pode ser conferido no código. Os textos dos artigos são arquivos .md, um por idioma, e os dados de cada artigo, como categoria, tópicos e fontes, ficam em arquivos YAML separados. As coleções de conteúdo do Astro leem esses arquivos com o loader glob() e os validam com schema no build. O projeto não instala a integração de MDX nem usa CMS.

Isso descreve a configuração atual, não uma recomendação geral. O detalhamento das coleções está em Content Collections do Astro.

O que levar deste texto

• Markdown é a base mais simples e portátil: texto puro, versionado com o código, com pouca coisa para dar errado.
• MDX acrescenta componentes ao texto, mas é código: sintaxe menos tolerante e uso restrito a autores confiáveis.
• CMS headless abre o site para equipes não técnicas, ao custo de mais um serviço, uma integração e, em sites estáticos, um build por mudança.
• Decida por quem escreve, quanto o conteúdo muda e quanto você aceita depender de terceiros. Combinar as opções é comum.