Coleções de Conteúdo

Adicionado em: astro@2.0.0

Coleções de conteúdo são a melhor forma de gerenciar e criar conteúdo em qualquer projeto Astro. Coleções ajudam a organizar seu documentos, validar seu frontmatter, e fornece checagem automática de tipos do TypeScript para todo seu conteúdo.

O que são Coleções de Conteúdo?

Uma coleção de conteúdo é qualquer pasta de nível superior dentro da pasta reservada do projeto src/content, como src/content/newsletter e src/content/autores. Apenas coleções de conteúdo são permitidas dentro da pasta src/content. Essa pasta não pode ser usada para nada além disso.

Uma entrada da coleção é qualquer peça de conteúdo armazenada dentro da sua pasta da coleção de conteúdo. Entradas podem usar formatos de autoria de conteúdo incluindo Markdown (.md) e MDX (.mdx usando a integração do MDX) ou como formatos de dados incluindo YAML (.yaml) e JSON (.json). Nós recomendamos usar um esquema de nomenclatura consistente (minúsculas, traços ao invés de espaços) para seus arquivos para tornar fácil de encontrar e organizar seu conteúdo, mas isso não é obrigatório. Você também pode excluir entradas de serem incluídas no build ao prefixar o nome do arquivo com um sublinhado (_).

Directorysrc/content/
- Directorynewsletter/ a coleção “newsletter”
  - semana-1.md uma entrada da coleção
  - semana-2.md uma entrada da coleção
  - semana-3.md uma entrada da coleção

Tendo a coleção, você pode começar a consultar seu conteúdo usando as APIs de conteúdo integradas no Astro.

A Pasta “.astro”

O Astro armazena metadados importantes para coleções de conteúdo em uma pasta .astro no seu projeto. Nenhuma ação é necessária da sua parte para manter ou atualizar essa pasta. Você é encorajado a ignorá-lo completamente enquanto estiver trabalhando no seu projeto.

A pasta .astro vai ser atualizada para você automaticamente sempre que você executa os comandos astro dev e astro build. Você pode executar astro sync a qualquer momento para atualizar a pasta .astro manualmente.

Se você está usando Git para controle de versão, nós recomendamos ignorar a pasta .astro adicionando .astro no seu .gitignore. Isso diz ao Git ignorar essa pasta e quaisquer arquivos dentro dela.

echo "\n.astro" >> .gitignore

Organizando com múltiplas coleções

Se dois arquivos representam diferentes tipos de conteúdo (por exemplo, uma postagem de blog e um perfil de autor), eles provavelmente pertencem a coleções diferentes. Isso é importante porque muitas funcionalidades (validação do frontmatter, segurança automática de tipo do TypeScript) requerem que todas as entradas em uma coleção compartilhem uma estrutura similar.

Se você se encontrar trabalhando com diferentes tipos de conteúdo, você deve criar múltiplas coleções para representar cada tipo. Você pode criar quantas coleções diferentes você quiser no seu projeto.

Directorysrc/content/
- Directorynewsletter/
  - semana-1.md
  - semana-2.md
- Directoryblog/
  - postagem-1.md
  - postagem-2.md
- Directoryautores/
  - grace-hopper.json
  - alan-turing.json

Organizando com subpastas

Uma coleção de conteúdo é sempre uma pasta no nível superior dentro da pasta src/content/. Você não pode aninhar uma coleção dentro da outra. Entretanto, você pode usar subpastas para organizar seu conteúdo dentro de uma coleção.

Por exemplo, você pode usar a seguinte estrutura de pasta para organizar traduções dentro de uma única coleção docs. Quando você consultar essa coleção, você vai ser capaz de filtrar o resultado pelo idioma usando o caminho do arquivo.

Directorysrc/content/
- Directorydocs/ essa coleção usa subpastas para organizar por idioma
  - Directoryen/
    …
  - Directoryes/
    …
  - Directoryde/
    …

Definindo Coleções

Para obter o máximo de suas coleções de conteúdo, crie um arquivo src/content/config.ts no seu projeto (extensões .js e .mjs também são suportadas). Esse é um arquivo especial que o Astro vai automaticamente carregar e usar para configurar suas coleções de conteúdo.

// 1. Importe utilitários do `astro:content`
import { defineCollection } from 'astro:content';
// 2. Defina sua(s) coleção(ões)
const colecaoBlog = defineCollection({ /* ... */ });
// 3. Exporte um único objeto `collections` para registrar sua(s) coleção(ões)
//    Essa chave deve corresponder com o nome da pasta da coleção em "src/content"
export const collections = {
  'blog': colecaoBlog,
};

Configurando o TypeScript

Se você ainda não estende as configurações recomendadas de TypeScript strict ou strictest do Astro no seu arquivo tsconfig.json, talvez você precise atualizar seu tsconfig.json para habilitar strictNullChecks.

{
  // Nota: Nenhuma alteração é necessária se você usa "astro/tsconfigs/strict" ou "astro/tsconfigs/strictest"
  "extends": "astro/tsconfigs/base",
  "compilerOptions": {
    "strictNullChecks": true
  }
}

Se você use arquivos .js ou .mjs em um projeto Astro, você pode habilitar o IntelliSense e checagem de tipo no seu editor ao habilitar allowJs no seu tsconfig.json:

{
  // Nota: Nenhuma alteração é necessária se você usa "astro/tsconfigs/strict" ou "astro/tsconfigs/strictest"
  "extends": "astro/tsconfigs/base",
  "compilerOptions": {
    "strictNullChecks": true,
    "allowJs": true
  }
}

Definindo um esquema de coleção

Os esquemas impõem dados consistentes de frontmatter ou de entrada em uma coleção. Um esquema garante que esses dados existam de forma previsível quando você precisar fazer referência a eles ou consultá-los. Se qualquer arquivo viola o esquema de sua coleção, o Astro vai fornecer um erro útil para informá-lo.

Os esquemas também compõe a tipagem automática de TypeScript do Astro para seu conteúdo. Quando você define um esquema para sua coleção, o Astro vai automaticamente gerar e aplicar uma interface do TypeScript para ela. O resultado é o suporte completo ao TypeScript quando você consulta sua coleção, incluindo o preenchimento automático de propriedades e a checagem de tipos

Para definir sua primeira coleção, crie um arquivo src/content/config.ts se um ainda não existir (extensões .js e .mjs também são suportadas). Esse arquivo deve:

Importar os utilitários adequados de astro:content.
Definir cada coleção que você gostaria de validar. Isso inclui um type (introduzido no Astro v2.5.0) especificando se a coleção contém formatos de autoria de conteúdo como Markdown (type: 'content') ou formatos de dados como JSON ou YAML (type: 'data'). Isso também inclui um schema que define o formato do seu frontmatter ou entrada de dados.
Exportar um único objeto collections para registrar suas coleções.

// 1. Importe utilitários do `astro:content`
import { z, defineCollection } from 'astro:content';

// 2. Defina um `type` e um `schema` para cada coleção
const colecaoBlog = defineCollection({
  type: 'content', // v2.5.0 e posterior
  schema: z.object({
    titulo: z.string(),
    tags: z.array(z.string()),
    imagem: z.string().optional(),
  }),
});

// 3. Exporte um único objeto `collections` para registrar sua(s) coleção(ões)
export const collections = {
  'blog': colecaoBlog,
};

Definindo múltiplas coleções

Você pode usar defineCollection() quantas vezes você quiser para criar vários esquemas. Todas as coleções devem ser exportadas de dentro de um único objeto collections.

const colecaoBlog = defineCollection({
  type: 'content',
  schema: z.object({ /* ... */ })
});
const newsletter = defineCollection({
  type: 'content',
  schema: z.object({ /* ... */ })
});
const autores = defineCollection({
  type: 'data',
  schema: z.object({ /* ... */ })
});

export const collections = {
  'blog': colecaoBlog,
  'newsletter': newsletter,
  'autores': autores,
};

Conforme seu projeto cresce, você também é livre para reorganizar sua base de código e mover a lógica para fora do arquivo src/content/config.ts. Definir seus esquemas separadamente pode ser útil para reutilizar esquemas através de múltiplas coleções e compartilhar esquemas com outras partes do seu projeto.

// 1. Importe seus utilitários e esquemas
import { defineCollection } from 'astro:content';
import { esquemaBlog, esquemaAutor } from '../schemas';

// 2. Defina suas coleções
const colecaoBlog = defineCollection({
  type: 'content',
  schema: esquemaBlog,
});
const colecaoAutor = defineCollection({
  type: 'data',
  schema: esquemaAutor,
});

// 3. Exporte várias coleções para registrá-las
export const collections = {
  'blog': colecaoBlog,
  'authors': colecaoAutor,
};

Usando esquemas de coleção de terceiros

Você pode importar esquemas de coleção de qualquer lugar, incluindo pacotes npm externos. Isso pode ser útil ao trabalhar com temas e bibliotecas que fornecem seus próprios esquemas de coleção para você usar.

import { esquemaBlog } from 'meu-tema-de-blog';
const colecaoBlog = defineCollection({ type: 'content', schema: esquemaBlog });

// Exporte a coleção do blog, usando um esquema externo do 'meu-tema-de-blog'
export const collections = {
  'blog': colecaoBlog,
};

Definindo tipos de dados com Zod

O Astro usa Zod para alimentar sues esquemas de conteúdo. Com Zod, o Astro é capaz de validar cada frontmatter dos arquivos dentro de uma coleção e fornecer tipos do TypeScript automaticamente quando você vai consultar conteúdo de dentro do seu projeto.

Para usar Zod no Astro, importe o utilitário z do "astro:content". Esse é uma reexportação da biblioteca Zod, e ele suporta todas as funcionalidades do Zod. Veja o README do Zod para a documentação completa de como o Zod funciona e quais funcionalidades estão disponíveis.

// Exemplo: Uma cheatsheet de muitos tipos de dados comuns com Zod
import { z, defineCollection } from 'astro:content';

defineCollection({
  schema: z.object({
    isRascunho: z.boolean(),
    titulo: z.string(),
    ordenacao: z.number(),
    imagem: z.object({
      src: z.string(),
      alt: z.string(),
    }),
    autor: z.string().default('Anônimo'),
    idioma: z.enum(['en', 'es']),
    tags: z.array(z.string()),
    // Uma propriedade opcional do frontmatter. Muito comum!
    notaRodape: z.string().optional(),
    // No frontmatter, datas escritas sem aspas envolta delas são interpretadas como objetos Date
    dataPublicacao: z.date(),
    // Você também pode transformar uma string de data (por exemplo, "2022-07-08") para um objeto Date
    // dataPublicacao: z.string().transform((str) => new Date(str)),
    // Avançado: Validar que a string também é um email
    contatoAutor: z.string().email(),
    // Avançado: Validar que a string também é uma URL
    URLCanonica: z.string().url(),
  })
})

Definindo referências de coleção

Entradas de coleções também podem “referenciar” outras entradas relacionadas.

Com a função reference() da API de Coleções, você pode definir uma propriedade de um esquema de coleção como uma entrada de outra coleção. Por exemplo, você pode exigir que todas as entradas nave-espacial incluam uma propriedade piloto que usa o esquema da coleção piloto para checagem de tipo, conclusão automática e validação.

Um exemplo comum é uma postagem de blog que referencia perfis de autor reutilizáveis armazenados como JSON, ou URLs de postagens relacionadas armazenadas na mesma coleção:

import { defineCollection, reference, z } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    titulo: z.string(),
    // Referencia um único autor da coleção `autores` pelo `id`
    autor: reference('autores'),
    // Referencia um array de postagens relacionadas da coleção `blog` pelo `slug`
    postagensRelacionadas: z.array(reference('blog')),
  })
});

const autores = defineCollection({
  type: 'data',
  schema: z.object({
    nome: z.string(),
    portfolio: z.string().url(),
  })
});

export const collections = { blog, autores };

Este exemplo de postagem de blog especifica os slugs de postagens relacionadas e o id do autor da postagem:

---
titulo: "Bem-vindo ao meu blog"
autor: ben-holmes # referencia `src/content/autores/ben-holmes.json`
postagensRelacionadas:
- sobre-mim # referencia `src/content/blog/sobre-mim.md`
- minha-retrospectiva # referencia `src/content/blog/minha-retrospectiva.md`
---

Definindo slugs customizados

Ao usar type: 'content', toda entrada de conteúdo gera uma propriedade slug amigável para URL a partir do seu id do arquivo. O slug é usado para consultar a entrada diretamente da sua coleção. Ela também é útil ao criar novas páginas e URLs do seu conteúdo.

Você pode sobrescrever a slug gerada para a entrada ao adicionar seu própria propriedade slug ao frontmatter do arquivo. Isso é similar à funcionalidade permalink de outros frameworks web. "slug é um nome de propriedade especial e reservada que não é permitida no seu schema customizado da coleção e não vai aparecer na propriedade data da sua entrada.

---
title: Minha Postagem de Blog
slug: minha-slug-customizada/suporta/barras
---
Seu conteúdo da postagem do blog vem aqui.

Consultando Coleções

O Astro fornece duas funções para consultar uma coleção e retornar um (ou mais) entradas de conteúdo: getCollection() e getEntry().

import { getCollection, getEntry } from 'astro:content';

// Obtém todas as entradas de uma coleção.
// Requer o nome da coleção como um argumento.
// Exemplo: recuperar `src/content/blog/**`
const todasPostagensDoBlog = await getCollection('blog');

// Obtém uma única entrada de uma coleção.
// Requer o nome da coleção e ou o `slug` da
// entrada (coleções de conteúdo) ou o `id` (coleções de dados)
// Exemplo: recuperar `src/content/autores/grace-hopper.json`
const perfilGraceHopper = await getEntry('autores', 'grace-hopper');

Ambas as funções retornam entradas de conteúdo definidas pelo tipo CollectionEntry.

Acessando dados referenciados

Quaisquer referências definidas no seu esquema precisam ser consultadas separadamente após primeiro consultar sua primeira entrada da coleção. Você pode usar a função getEntry() de novo ou getEntries(), para recuperar a entrada referenciada a do objeto data retornado.

---
import { getEntry, getEntries } from 'astro:content';

const postagemBlog = await getEntry('blog', 'bem-vindo');

// Recupera um única referencia
const autor = await getEntry(postagemBlog.data.autor);
// Recupera um array de referências
const postagensRelacionadas = await getEntries(postagemBlog.data.postagensRelacionadas);
---

<h1>{postagemBlog.data.titulo}</h1>
<p>Autor: {autor.data.nome}</p>

<!-- ... -->

<h2>Você também pode gostar:</h2>
{postagensRelacionadas.map(p => (
  <a href={p.slug}>{p.data.titulo}</a>
))}

Filtrando consultas de coleção

getCollection() recebe um callback opcional “filter” que permite que você filtre sua consulta baseado em um id ou propriedades do data (frontmatter) da entrada. Para coleções type: 'content', você também pode filtrar baseado no slug.

Você pode usar isso para filtrar por qualquer critério de conteúdo que você quiser. Por exemplo, você pode filtrar por propriedades como draft para evitar que quaisquer postagens do blog em rascunho sejam publicadas para seu blog:

// Exemplo: Filtrar entradas de conteúdo com `draft: true`
import { getCollection } from 'astro:content';
const entradasPublicadasBlog = await getCollection('blog', ({ data }) => {
  return data.draft !== true;
});

Você também pode criar páginas de rascunho que são disponibilizadas ao executar o servidor de desenvolvimento, mas não são construídas em produção:

// Exemplo: Filtrar entradas de conteúdo com `draft: true` apenas ao fazer build para produção
import { getCollection } from 'astro:content';
const entradasBlog = await getCollection('blog', ({ data }) => {
  return import.meta.env.PROD ? data.draft !== true : true;
});

O argumento de filtragem também suporta filtragem por pastas aninhadas dentro de uma coleção. Já que o id inclui o caminho aninhado completo, você pode filtrar pelo começo de cada id para retornar somente itens de uma pasta aninhada específica:

// Exemplo: Filtrar entradas por sub-pasta em uma coleção
import { getCollection } from 'astro:content';
const entradasDocsIngles = await getCollection('docs', ({ id }) => {
  return id.startsWith('en/');
});

Usando conteúdo em templates do Astro

Uma vez que você tenha consultado suas entradas de coleção, você pode acessar cada entrada diretamente do template do seu componente Astro. Isso permite que você renderize HTML para coisas como links para seu conteúdo (usando o slug do conteúdo) ou informação sobre seu conteúdo (usando a propriedade data).

Para informações sobre renderizando seu conteúdo para HTML, veja Renderizando Conteúdo para HTML abaixo.

---
import { getCollection } from 'astro:content';
const entradasBlog = await getCollection('blog');
---
<ul>
  {entradasBlog.map(entradaPostagemBlog => (
    <li>
      <a href={`/minha-url-do-blog/${entradaPostagemBlog.slug}`}>{entradaPostagemBlog.data.titulo}</a>
      <time datetime={entradaPostagemBlog.data.dataPublicacao.toISOString()}>
        {entradaPostagemBlog.data.dataPublicacao.toDateString()}
      </time>
    </li>
  ))}
</ul>

Passando conteúdo como props

Um componente também pode passar uma entrada de conteúdo inteira como prop.

Se você fizer isso, você pode usar o utilitário CollectionEntry para definir corretamente o tipo de props de seus componentes usando TypeScript. Esse utilitário recebe uma string como argumento que corresponde com o nome do esquema da sua coleção e vai herdar todas as propriedades desse esquema de coleção.

---
import type { CollectionEntry } from 'astro:content';
interface Props {
  postagem: CollectionEntry<'blog'>;
}

// `postagem` vai corresponder com o tipo do esquema de coleção 'blog'
const { postagem } = Astro.props;
---

Renderizando conteúdo para HTML

Uma vez consultada, você pode renderizar entradas Markdown e MDX para HTML usando a propriedade de função render() da entrada. A chamada dessa função lhe dá acesso ao conteúdo e aos metadados renderizados, incluindo um componente <Content /> e uma lista de todos os cabeçalhos renderizados.

---
import { getEntry } from 'astro:content';
const entrada = await getEntry('blog', 'postagem-1');
const { Content, headings } = await entry.render();
---
<p>Publicado em: {entry.data.publicado.toDateString()}</p>
<Content />

Gerando Rotas a partir do Conteúdo

Coleções de conteúdo são armazenadas fora da pasta src/pages/. Isso significa que nenhuma rota é gerada para seus itens de coleção por padrão. Você vai precisar criar manualmente uma nova rota dinâmica para gerar páginas HTML das suas entradas de coleção. Sua rota dinâmica vai mapear os parâmetros de requisição recebidos (por exemplo, Astro.params.slug em src/pages/blog/[...slug].astro) para buscar a entrada correta dentro de uma coleção.

O método exato para gerar rotas vai depender do modo output da sua build: ‘static’ (o padrão) ou ‘server’ (para SSR).

Fazendo a build para saída estática (padrão)

Se você está construindo um website estático (comportamento padrão do Astro), você usaria a função getStaticPaths() para criar múltiplas páginas a partir de um único componente no src/pages/ durante seu build.

Chame getCollection() dentro de getStaticPaths() para consultar sua coleção de conteúdo ou de dados. Em seguida, crie seus novos caminhos de URL usando a propriedade slug (coleções de conteúdo) ou a propriedade id (coleções de dados) de cada entrada de conteúdo.

---
import { getCollection } from 'astro:content';
// 1. Gere um novo caminho para cada entrada da coleção
export async function getStaticPaths() {
  const entradasBlog = await getCollection('blog');
  return entradasBlog.map(entrada => ({
    params: { slug: entrada.slug }, props: { entrada },
  }));
}
// 2. Quando for hora de renderizar, você pode pegar e entrada diretamente da prop
const { entrada } = Astro.props;
const { Content } = await entrada.render();
---
<h1>{entrada.data.titulo}</h1>
<Content />

Isso vai gerar uma nova página para cada entrada na coleção blog. Por exemplo, uma entrada em src/content/blog/ola-mundo.md vai ter a slug ola-mundo e portanto sua URL final vai ser /postagens/ola-mundo/.

Fazendo a build para saída de servidor (SSR)

Se você está construindo um website dinâmico (usando o suporte a SSR do Astro), não é esperado que você gerará nenhum caminho de antemão durante a build. Ao invés disso, sua página deve examinar a requisição (usando Astro.request ou Astro.params) para encontrar o slug sob demanda e então buscar ele usando getEntry().

---
import { getEntry } from "astro:content";
// 1. Pega o slug da requisição recebida pelo servidor
const { slug } = Astro.params;
if (slug === undefined) {
  throw new Error("O slug é obrigatório");
}
// 2. Consulta pela entrada diretamente usando o slug da requisição
const entrada = await getEntry("blog", slug);
// 3. Redireciona se a entrada não existir
if (entrada === undefined) {
  return Astro.redirect("/404");
}
// 4. (Opcional) Renderiza a entrada para HTML no template
const { Content } = await entrada.render();
---

Migrando do Roteamento Baseado em Arquivos

Se você tiver um projeto Astro existente, como um blog, que utiliza arquivos Markdown ou MDX em subpastas dentro de src/pages/, considere migrar conteúdo relacionado ou arquivos de dados para coleções de conteúdo.

Veja como converter um exemplo básico de blog de src/pages/posts/ para src/content/posts em nosso tutorial passo a passo que utiliza o código-fonte do projeto final do tutorial Construa um Blog.

Habilitando o Cache de Build

Adicionado em: astro@3.5.0 Experimental

Se você estiver trabalhando com coleções grandes, talvez queira ativar builds com cache com a flag experimental.contentCollectionCache. Essa funcionalidade experimental otimiza o processo de build do Astro, permitindo que coleções inalteradas sejam armazenadas e reutilizadas entre builds.

Em muitos casos, isso pode levar a melhorias significativas no desempenho de build.

Enquanto essa funcionalidade se estabiliza, você pode ter problemas com o cache armazenado. Você sempre pode redefinir o cache de build executando o seguinte comando:

npm run astro build -- --force

Modificando o Frontmatter com Remark

Astro suporta plugins remark ou rehype que modificam seu frontmatter diretamente. Você pode acessar esse frontmatter modificado dentro de uma entrada de conteúdo usando a propriedade remarkPluginFrontmatter retornada do render():

---
import { getEntry } from 'astro:content';
const postagemBlog = await getEntry('blog', 'postagem-1');
const { remarkPluginFrontmatter } = await postagemBlog.render();
---
<p>{postagemBlog.data.titulo} — {remarkPluginFrontmatter.tempoLeitura}</p>

Receita relacionada: Adicione tempo de leitura

Os pipelines do remark e rehype executam quando seu conteúdo é renderizado, que explica o porquê de remarkPluginFrontmatter só estar disponível depois de você chamar render() na sua entrada de conteúdo. Em contraste, getCollection() e getEntry() não podem retornar esses valores diretamente porque eles não renderizam seu conteúdo.

Trabalhar com datas no frontmatter

Vários formatos de data são possíveis em coleções de conteúdo, mas o esquema de sua coleção deve corresponder ao formato usado em seu frontmatter de Markdown ou MDX YAML.

O YAML usa o padrão ISO-8601 para expressar datas. Use o formato yyyy-mm-dd (por exemplo, 2021-07-28) junto com um tipo de esquema z.date():

---
titulo: Minha Postagem de Blog
dataPublicacao: 2021-07-08
---

O formato da data será especificado em UTC se não for fornecido um fuso horário. Se você precisar especificar um fuso horário, poderá usar o formato ISO 8601.

---
titulo: Minha Postagem de Blog
dataPublicacao: 2021-07-08T12:00:00-04:00
---

Para renderizar somente o YYYY-MM-DD do registro de data e hora UTC completo, use o método slice do JavaScript para remover o registro de data e hora:

---
const { frontmatter } = Astro.props;
---
<h1>{frontmatter.titulo}</h1>
<p>{frontmatter.dataPublicacao.toString().slice(0,10)}</p>

Para ver um exemplo de uso de toLocaleDateString para formatar o dia, o mês e o ano, consulte o componente <FormattedDate /> no template oficial do blog do Astro.

Contribua

Comunidade