Markdown, MDX e Content Collections
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.propsconst { 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() |
