Procedimento para Páginas de Conteúdo
Procedimento passo a passo para criar páginas orientadas por conteúdo usando Astro Content Collections (Content Layer API) com roteamento dinâmico.
Pré-requisitos
src/styles/global.cssexiste com os tokens de design (criado por css-procedure)docs/stitch/reference.mdexiste (informações de campo das telas Stitch)
Entrada / Saída
[Entrada] [Saída]
docs/stitch/reference.md ──┐
(Informações de campo da tela) │
progress.md notes ──────────┼──→ src/content/config.ts (schema)
(Estrutura de seção, │ src/content/<coleção>/<slug>/index.mdx (dados)
decisões de design) │ src/pages/<coleção>/[...slug].astro (roteamento)
│ src/components/*.astro (componentes de seção)
Passos
Passo 1: Definição do Schema (src/content/config.ts)
Astro 5 Content Layer API usa o loader glob.
1-1. Definir Coleção
import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";
const myCollection = defineCollection({
loader: glob({ pattern: "**/index.mdx", base: "./src/content/minha-colecao" }),
schema: ({ image }) =>
z.object({
title: z.string(),
// ... defina os campos
heroImage: image(), // Use o helper image() para imagens
}),
});
export const collections = { myCollection };
1-2. Diretrizes de Design do Schema
- Comece mínimo, estenda incrementalmente. Defina apenas os campos necessários para a renderização atual da página; adicione mais ao implementar componentes
- Use o helper
image()para campos de imagem para habilitar validação de caminho e otimização em tempo de build - Use
.optional()para campos que não são obrigatórios em todas as entradas - Use arrays opcionais para dados no nível de seção para controlar a visibilidade da seção por página:
// Schema moments: z.array(z.object({ title: z.string(), ... })).optional()<!-- Template de página: renderização condicional --> {data.moments && <MomentsSection moments={data.moments} />}
1-3. Armadilhas do YAML Frontmatter
- Nomes de meses (Março, Maio, etc.) e Sim/Não são convertidos automaticamente pelo YAML. Coloque-os entre aspas se devem ser strings:
date: "Março" - Caminhos de imagem são relativos ao arquivo MDX:
heroImage: ./hero.jpg
Passo 2: Criar Dados de Conteúdo
2-1. Estrutura de Diretórios
src/content/<coleção>/<slug>/
├── index.mdx # frontmatter + corpo MDX
├── hero.jpg # Imagens co-localizadas com o conteúdo
└── ...
2-2. Estrutura do Arquivo MDX
---
title: "Título da Página"
heroImage: ./hero.jpg
description: "Texto de descrição"
---
## Corpo MDX
O conteúdo do corpo é recuperado via `render()` e renderizado como `<Content />`.
2-3. Gerenciamento de Imagens
- Armazene imagens dentro de
src/content/co-localizadas com seu conteúdo (não empublic/) - Redimensione imagens maiores que 2560px antes de commitar
- Ao usar o helper
image()no schema, os caminhos de imagem no frontmatter resolvem para o tipoImageMetadata. UseImageMetadatatambém nas Props do componente
Passo 3: Página de Roteamento Dinâmico
Crie src/pages/<coleção>/[...slug].astro:
---
import type { GetStaticPaths } from "astro";
import { getCollection, render } from "astro:content";
export const getStaticPaths = (async () => {
const items = await getCollection("myCollection");
return items.map((item) => ({
params: { slug: item.id },
props: { item },
}));
}) satisfies GetStaticPaths;
const { item } = Astro.props;
const { Content } = await render(item);
---
Pontos-chave
getCollection()busca todas as entradas;getStaticPathsgera caminhos estáticosrender()retorna o corpo MDX como um componenteContentitem.datafornece acesso type-safe aos campos do frontmatter- Renderização condicional para campos opcionais:
{data.field && <Component ... />}
Passo 4: Arquivos de Dados da Página (src/data/<página>.md)
Conteúdo editável pelo usuário (texto, rótulos, URLs) para cada página deve ser definido em arquivos Markdown com YAML frontmatter sob src/data/. Isso mantém o formato consistente com Content Collections e facilita para os usuários encontrarem e editarem seu conteúdo.
Nota: O diretório
src/data/não é criado pelo skill de scaffold. Crie-o neste passo.
4-1. Crie um arquivo de dados para cada página
src/data/
├── index.md # Conteúdo da página Works (Topo)
├── about.md # Conteúdo da página Sobre Mim
└── skills.md # Conteúdo da página Habilidades
4-2. Defina o conteúdo editável como YAML frontmatter
---
# ==============================
# Conteúdo da Página Works
# Edite este arquivo para personalizar sua página.
# ==============================
hero:
headingPrefix: "Olá, sou um"
highlightedText: "Desenvolvedor Web."
description: "Construo aplicações escaláveis e centradas no usuário..."
badgeText: "Disponível para novos projetos"
cta:
heading: "Pronto para construir algo juntos?"
description: "Estou atualmente aberto a oportunidades freelance..."
buttons:
- label: "Entre em Contato"
href: "mailto:[email protected]"
variant: "primary"
- label: "Baixar Currículo"
href: "#"
variant: "secondary"
---
- Coloque apenas texto editável pelo usuário no YAML (strings, rótulos, URLs, arrays de texto)
- Mantenha dados não editáveis (caminhos de ícones SVG, etc.) como constantes TypeScript no arquivo
.astroda página
4-3. Importe dados na página
Use import.meta.glob() para carregar o frontmatter:
---
const content = Object.values(
import.meta.glob("../data/index.md", { eager: true })
)[0] as { frontmatter: Record<string, unknown> };
const { hero, cta } = content.frontmatter;
---
Passo 5: Implementação de Componentes de Seção
Crie cada seção (hero, moments, etc.) como um componente independente em src/components/.
Siga as diretrizes de desenvolvimento para estrutura de componentes e regras CSS.
Exibição de Imagens: <Picture> vs <img>
| Método | Quando usar | Exemplo |
|---|---|---|
<Picture> | Imagens estáticas conhecidas em tempo de build | Fundos hero, imagens de entrada |
<img> | Imagens trocadas dinamicamente por JS do cliente | Slideshows de galeria modal |
<Picture> renderiza em tempo de build, portanto não pode ser usado quando a src é trocada por JS do cliente.
JavaScript do Lado do Cliente
Tags <script> em componentes Astro executam como JS do cliente. Funcionalidades interativas podem ser construídas sem frameworks (React, etc.).
Padrão de passagem de dados: Use atributos data-* para passar dados do frontmatter para o JS do cliente. <script> não pode referenciar diretamente variáveis do frontmatter.
Acessibilidade: Modal / Sobreposição
Checklist para implementação de diálogo modal:
| Requisito | Implementação |
|---|---|
| Semântica | role="dialog" + aria-modal="true" + aria-label |
| Abrir/fechar | Alternar atributo hidden + transição CSS opacity |
| Bloqueio de scroll | Abrir: document.body.style.overflow = "hidden" / Fechar: restaurar para "" |
| Teclado | Escape para fechar, teclas de seta para navegação |
| Foco preso | Tab/Shift+Tab percorre apenas botões dentro do modal |
| Restaurar foco | focus() no elemento disparador ao fechar |
| Fechar ao fundo | Fechar quando o clique alvo não for um elemento interativo |
| z-index | Maior que elementos fixos existentes (ex.: header 50 → modal 60) |
Passo 6: Verificação de Build
npm run build
Erros de validação de schema de Content Collections aparecem em tempo de build com mensagens claras.
Erros Comuns
| Erro | Causa | Correção |
|---|---|---|
Expected type "string", received "object" | YAML converteu um valor automaticamente (nome de mês → Date, etc.) | Coloque o valor entre aspas |
Could not find image | Caminho de imagem incorreto | Verifique o caminho relativo a partir do arquivo MDX |
does not match collection schema | Campo ausente ou tipo incompatível no frontmatter | Verifique o schema em config.ts |
Passo 7: Verificação do Servidor de Desenvolvimento
npm run dev
- Alterações no schema podem exigir reinicialização do servidor de desenvolvimento (limpeza do armazenamento de conteúdo)
- Se os erros persistirem após a reinicialização, exclua o diretório
.astro/e reinicie
Checklist
-
src/content/config.tstem o schema definido - O frontmatter MDX está em conformidade com o schema
- As imagens estão dentro de
src/content/e redimensionadas para ≤2560px -
[...slug].astroretorna todas as entradas degetStaticPaths - As seções de campo opcional usam renderização condicional
-
npm run buildé bem-sucedido - Confirmação visual no navegador para todas as seções (incluindo largura mobile)