Ir para o conteúdo
Promovaweb

Markdown, MDX e Content Collections

Revisado em

O Astro transforma Markdown em HTML e aceita MDX com uma integração. As Content Collections agrupam entradas de conteúdo com schema de validação e funções de consulta.

Formatos de conteúdo

Formato Uso no Astro Suporte
Markdown, .md Texto com títulos, links, imagens e blocos de código Nativo
MDX, .mdx Markdown com expressões JSX e componentes importados Integração @astrojs/mdx
Frontmatter Campos YAML entre cercas --- no início do arquivo Disponível em Markdown e MDX

Arquivos Markdown em src/pages/ geram rotas pelo caminho do arquivo. Entradas de uma coleção precisam de uma página que consulte e renderize o conteúdo.

Arquivos e loaders

Item Função
src/content.config.ts Declara as coleções exportadas pelo projeto
glob() Carrega vários arquivos locais por padrão de caminho
file() Carrega várias entradas de um arquivo JSON, YAML ou TOML
base do glob() Diretório de busca dos arquivos
pattern do glob() Padrão de seleção, como **/*.md
schema Define os campos e seus tipos com Zod

O loader do exemplo busca arquivos em src/content/artigos/:

import { defineCollection } from 'astro:content'
import { glob } from 'astro/loaders'
import { z } from 'astro/zod'
const artigos = defineCollection({
loader: glob({ base: './src/content/artigos', pattern: '**/*.md' }),
schema: z.object({
title: z.string(),
description: z.string(),
pubDate: z.coerce.date(),
draft: z.boolean().default(false)
})
})
export const collections = { artigos }

Campos do frontmatter

Os nomes abaixo pertencem ao schema do exemplo. Cada coleção define os próprios campos.

Campo Tipo no schema Comportamento
title z.string() Texto obrigatório
description z.string() Texto obrigatório
pubDate z.coerce.date() Converte o valor para uma data
draft z.boolean().default(false) Usa false quando o campo está ausente
---
title: 'Referência de conteúdo'
description: 'Formatos aceitos pela coleção de artigos.'
pubDate: 2026-11-06
---
O corpo do artigo fica abaixo do frontmatter.

Consulta e renderização

Função ou propriedade Retorno ou uso
getCollection('artigos') Lista de entradas da coleção
getEntry('artigos', id) Uma entrada pelo identificador
entry.id Identificador da entrada
entry.data Campos validados pelo schema
render(entry) Componente Content e informações da renderização
getStaticPaths() Define os caminhos de uma rota dinâmica estática

Uma página src/pages/artigos/[...id].astro pode gerar um caminho por entrada, incluindo identificadores com subpastas:

---
import { getCollection, render } from 'astro:content'
export async function getStaticPaths() {
const artigos = await getCollection('artigos', ({ data }) => !data.draft)
return artigos.map((artigo) => ({
params: { id: artigo.id },
props: { artigo }
}))
}
const { artigo } = Astro.props
const { Content } = await render(artigo)
---
<h1>{artigo.data.title}</h1>
<Content />

O filtro exclui rascunhos desses caminhos. A ordem de getCollection() não é fixa, então uma listagem por data exige ordenação explícita.

Integração MDX

Configuração Valor
Instalação npx astro add mdx
Extensão .mdx
Padrão para Markdown e MDX no loader **/*.{md,mdx}
Componentes no texto Importação seguida da tag do componente

A ficha do @astrojs/mdx detalha a integração.

Falhas de conteúdo

Sintoma Causa e conferência
InvalidContentEntryDataError Uma entrada não corresponde ao schema. A mensagem identifica a coleção e os campos inválidos
Arquivo ausente na consulta Conferir base, pattern e o filtro de getCollection()
Texto ausente na página Conferir a chamada de render() e a presença de <Content />
Entrada sem URL pública Conferir o arquivo em src/pages/ e os caminhos de getStaticPaths()
StayCloud

Uma VPS para desenvolver com agentes

Servidor da StayCloud em São Paulo, com acesso root e disco NVMe, para deixar seus agentes de IA rodando o dia todo.

Montar minha VPS

Link de parceiro da Promovaweb.