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?
Seção intitulada 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”
Seção intitulada 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.
Organizando com múltiplas coleções
Seção intitulada Organizando com múltiplas coleçõesSe 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
Seção intitulada Organizando com subpastasUma 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
Seção intitulada Definindo ColeçõesO arquivo src/content/config.ts
é opcional. Entretanto, escolher não definir suas coleções vai desabilitar algumas das suas melhores funcionalidades como validação do esquema do frontmatter ou tipagem automática do TypeScript.
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.
Configurando o TypeScript
Seção intitulada Configurando o TypeScriptSe 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
.
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
:
Definindo um esquema de coleção
Seção intitulada Definindo um esquema de coleçãoOs 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 umschema
que define o formato do seu frontmatter ou entrada de dados. - Exportar um único objeto
collections
para registrar suas coleções.
Definindo múltiplas coleções
Seção intitulada Definindo múltiplas coleçõesVocê 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
.
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.
Usando esquemas de coleção de terceiros
Seção intitulada Usando esquemas de coleção de terceirosVocê 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.
Definindo tipos de dados com Zod
Seção intitulada Definindo tipos de dados com ZodO 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.
Definindo referências de coleção
Seção intitulada Definindo referências de coleçãoEntradas 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:
Este exemplo de postagem de blog especifica os slug
s de postagens relacionadas e o id
do autor da postagem:
Definindo slugs customizados
Seção intitulada Definindo slugs customizadosAo 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.
Consultando Coleções
Seção intitulada Consultando ColeçõesO Astro fornece duas funções para consultar uma coleção e retornar um (ou mais) entradas de conteúdo: getCollection()
e getEntry()
.
Ambas as funções retornam entradas de conteúdo definidas pelo tipo CollectionEntry
.
Acessando dados referenciados
Seção intitulada Acessando dados referenciadosQuaisquer 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.
Filtrando consultas de coleção
Seção intitulada Filtrando consultas de coleçãogetCollection()
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
.
A propriedade slug
é específica para coleções de conteúdo e não vai estar disponível ao filtrar coleções de JSON ou YAML.
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:
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:
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:
Usando conteúdo em templates do Astro
Seção intitulada Usando conteúdo em templates do AstroUma 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.
Passando conteúdo como props
Seção intitulada Passando conteúdo como propsUm 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.
Renderizando conteúdo para HTML
Seção intitulada Renderizando conteúdo para HTMLUma 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.
Gerando Rotas a partir do Conteúdo
Seção intitulada Gerando Rotas a partir do ConteúdoColeçõ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ção intitulada 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.
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/
.
Se seus slugs customizados incluem o caractere /
para produzir URLs com múltiplos segmentos no caminho, você precisa usar um parâmetro rest ([...caminho]
) no nome do arquivo .astro
nessa página de rota dinâmica.
Fazendo a build para saída de servidor (SSR)
Seção intitulada 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()
.
Migrando do Roteamento Baseado em Arquivos
Seção intitulada Migrando do Roteamento Baseado em ArquivosSe 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
Seção intitulada 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:
Modificando o Frontmatter com Remark
Seção intitulada Modificando o Frontmatter com RemarkNão recomendado. Os plugins remark e rehype acessam o frontmatter bruto do documento Markdown ou MDX. Isso significa que o frontmatter do remarkPluginFrontmatter
é tratado separadamente do seu schema
com segurança de tipos e não refletirá nenhuma alteração ou padrão aplicado pelo Astro. Use por sua conta e risco!
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()
:
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
Seção intitulada Trabalhar com datas no frontmatterVá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()
:
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.
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:
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.