Skip to content

Latest commit

 

History

History
376 lines (256 loc) · 13.8 KB

astro-content.mdx

File metadata and controls

376 lines (256 loc) · 13.8 KB
title i18nReady tableOfContents
Référence de l'API des collections de contenu
true
minHeadingLevel maxHeadingLevel
2
6

import Since from '/components/Since.astro'; import ReadMore from '/components/ReadMore.astro';

Les collections de contenu proposent des API pour configurer et interroger vos documents Markdown ou MDX dans src/content/. Pour connaître les fonctionnalités et les exemples d'utilisation, consultez notre guide sur les collections de contenu.

Importations depuis astro:content

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

defineCollection()

Type : (input: CollectionConfig) => CollectionConfig

defineCollection() est un utilitaire pour configurer une collection dans un fichier src/content/config.*.

// src/content/config.ts
import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    permalink: z.string().optional(),
  }),
});

// Exposez votre collection définie à Astro
// avec l'exportation `collections`
export const collections = { blog };

Cette fonction accepte les propriétés suivantes :

type

Type : 'content' | 'data'
Par défaut : 'content'

type est une chaîne de caractères qui définit le type d'entrées stockées dans une collection :

  • 'content' - pour les formats de création de contenu comme Markdown (.md), MDX (.mdx) ou Markdoc (.mdoc)
  • 'data' - pour les formats de données uniquement comme JSON (.json) ou YAML (.yaml)

:::tip Cela signifie que les collections ne peuvent pas stocker un mélange de contenus et de formats de données. Vous devez diviser ces entrées en collections distinctes par type. :::

schema

Type : ZodType | (context: SchemaContext) => ZodType

schema est un objet Zod facultatif pour configurer le type et la forme du document pour une collection. Chaque valeur doit utiliser un validateur Zod.

Consultez le guide Collections de contenu pour un exemple d'utilisation.

reference()

Type : (collection: string) => ZodEffects<ZodString, { collection, id: string } | { collection, slug: string }>

La fonction reference() est utilisée dans la configuration du contenu pour définir une relation, ou une « référence », entre une collection et une autre. Elle accepte un nom de collection et valide le ou les identifiants d'entrée spécifiés dans le frontmatter de votre contenu ou dans votre fichier de données.

Cet exemple définit les références d'un auteur de blog à la collection authors et un tableau d'articles associés à la même collection blog :

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

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    // Référence un seul auteur de la collection `authors` par `id`
    author: reference('authors'),
    // Référence un tableau d'articles connexes de la collection `blog` par `slug`
    relatedPosts: z.array(reference('blog')),
  })
});

const authors = defineCollection({
  type: 'data',
  schema: z.object({ /* ... */ })
});

export const collections = { blog, authors };

Consultez le guide Collections de contenu pour un exemple d'utilisation.

getCollection()

Type : (collection: string, filter?: (entry: CollectionEntry<TCollectionName>) => boolean) => CollectionEntry<TCollectionName>[]

getCollection() est une fonction qui récupère une liste d'entrées de collection de contenu par nom de collection.

Il renvoie tous les éléments de la collection par défaut et accepte une fonction facultative filter pour affiner les propriétés d'entrée. Cela vous permet d'interroger uniquement certains éléments d'une collection en fonction de id, slug ou des valeurs du frontmatter via l'objet data.

---
import { getCollection } from 'astro:content';

// Récupère toutes les entrées `src/content/blog/`
const allBlogPosts = await getCollection('blog');

// Ne renvoie que les messages avec `draft: true` dans le frontmatter
const draftBlogPosts = await getCollection('blog', ({ data }) => {
  return data.draft === true;
});
---

Consultez le guide Collections de contenu pour un exemple d'utilisation.

getEntry()

Types :

  • (collection: string, contentSlugOrDataId: string) => CollectionEntry<TCollectionName>
  • ({ collection: string, id: string }) => CollectionEntry<TCollectionName>
  • ({ collection: string, slug: string }) => CollectionEntry<TCollectionName>

getEntry() est une fonction qui récupère une seule entrée de collection en utilisant le nom de la collection et soit l'entrée id (pour les collections utilisant type: 'data') soit l'entrée slug (pour les collections utilisant type: 'content'). getEntry() peut également être utilisée pour obtenir des entrées référencées pour accéder aux propriétés data, body ou render() :

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

// Récupère `src/content/blog/enterprise.md`
const enterprisePost = await getEntry('blog', 'enterprise');

// Récupère `src/content/captains/picard.yaml`
const picardProfile = await getEntry('captains', 'picard');

// Récupère le profil référencé par `data.captain`
const enterpriseCaptainProfile = await getEntry(enterprisePost.data.captain);
---

Consultez le guide Collections de contenu pour des exemples d'interrogation des entrées de collection.

getEntries()

Types :

  • (Array<{ collection: string, id: string }>) => CollectionEntry<TCollectionName>[]
  • (Array<{ collection: string, slug: string }>) => CollectionEntry<TCollectionName>[]

getEntries() est une fonction qui récupère plusieurs entrées dans une même collection. Ceci est utile pour renvoyer un tableau d'entrées référencées pour accéder à leurs propriétés data, body et render() associées.

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

const enterprisePost = await getEntry('blog', 'enterprise');

// Récupère les articles associés référencés par `data.ratedPosts`
const enterpriseRelatedPosts = await getEntries(enterprisePost.data.relatedPosts);
---

getEntryBySlug()

Type : (collection: string, slug: string) => Promise<CollectionEntry<TCollectionName>>

:::caution[Obsolète] Utilisez la fonction getEntry() pour interroger les entrées de contenu. Elle accepte les mêmes arguments que getEntryBySlug() et prend en charge les requêtes par id pour les collections JSON ou YAML. :::

getEntryBySlug() est une fonction qui récupère une seule entrée de collection en utilisant le nom de la collection et le slug d'une entrée.

---
import { getEntryBySlug } from 'astro:content';

const enterprise = await getEntryBySlug('blog', 'enterprise');
---

Consultez le guide Collections de contenu pour un exemple d'utilisation.

getDataEntryById()

Type : (collection: string, id: string) => Promise<CollectionEntry<TCollectionName>>

:::caution[Obsolète] Utilisez la fonction getEntry() pour interroger les entrées de données. Cela accepte les mêmes arguments que getDataEntryById() et prend en charge l'interrogation par slug pour les formats de création de contenu comme Markdown. :::

getDataEntryById() est une fonction qui récupère une seule entrée de collection par nom de collection et par id d'entrée.

---
import { getDataEntryById } from 'astro:content';

const picardProfile = await getDataEntryById('captains', 'picard');
---

Types d'astro:content

import type {
  CollectionEntry,
  CollectionKey,
  ContentCollectionKey,
  DataCollectionKey,
  SchemaContext,
 } from 'astro:content';

CollectionEntry

Les fonctions de requête, notamment getCollection(), getEntry() et getEntries() renvoient chacune des entrées avec le type CollectionEntry. Ce type est disponible en tant qu'utilitaire depuis astro:content :

import type { CollectionEntry } from 'astro:content';

CollectionEntry est un type générique. Utilisez-le avec le nom de la collection que vous interrogez. Par exemple, une entrée de votre collection blog aurait le type CollectionEntry<'blog'>.

Chaque CollectionEntry est un objet avec les valeurs suivantes :

id

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Exemple de types :

  • collections de contenu : 'entry-1.md' | 'entry-2.md' | ...
  • collections de données : 'author-1' | 'author-2' | ...

Un identifiant unique utilisant le chemin du fichier relatif à src/content/[collection]. Énumère toutes les valeurs de chaîne de caractères possibles en fonction des chemins d’accès au fichier d’entrée de collection. Notez que les collections définies comme type: 'content' incluent l'extension de fichier dans leur identifiant, contrairement aux collections définies comme type: 'data'.

collection

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Exemple de type : 'blog' | 'authors' | ...

Le nom d'un dossier placé à la racine de src/content/ et dans lequel se trouvent les entrées. Il s'agit du nom utilisé pour référencer la collection dans votre schéma et dans les fonctions de requête.

data

Disponible pour : les collections utilisant type: 'content' ou type: 'data'
Type : CollectionSchema<TCollectionName>

Un objet de propriétés provenant du frontmatter et déduit de votre schéma de collection (voir la référence defineCollection()). La valeur par défaut est any si aucun schéma n'est configuré.

slug

Disponible pour : les collections utilisant type: 'content' seulement
Exemple de type : 'entry-1' | 'entry-2' | ...

Un slug d'URL préparé pour les documents Markdown ou MDX. La valeur par défaut est id sans l'extension de fichier, mais peut être remplacée en définissant la propriété slug dans le frontmatter d'un fichier.

body

Disponible pour : les collections utilisant type: 'content' seulement
Type : string

Une chaîne de caractères contenant le corps brut et non compilé du document Markdown ou MDX.

render()

Disponible pour : les collections utilisant type: 'content' seulement
Type : () => Promise<RenderedEntry>

Une fonction pour compiler un document Markdown ou MDX donné à afficher. Cela renvoie les propriétés suivantes :

---
import { getEntryBySlug } from 'astro:content';
const entry = await getEntryBySlug('blog', 'entry-1');

const { Content, headings, remarkPluginFrontmatter } = await entry.render();
---

Consultez le guide Collections de contenu pour un exemple d'utilisation.

CollectionKey

Une union de chaînes de caractères de tous les noms de collections définis dans votre fichier src/content/config.*. Ce type peut être utile lors de la définition d'une fonction générique qui accepte n'importe quel nom de collection.

import { type CollectionKey, getCollection } from 'astro:content';

async function getCollection(collection: CollectionKey) {
  return getCollection(collection);
}

ContentCollectionKey

Une union de chaînes de caractères de tous les noms des collections type: 'content' définies dans votre fichier src/content/config.*.

DataCollectionKey

Une union de chaînes de caractères de tous les noms de la collection type: 'data' définie dans votre fichier src/content/config.*.

SchemaContext

L'objet context que defineCollection utilise pour la forme de fonction du schema. Ce type peut être utile lors de la création de schémas réutilisables pour plusieurs collections.

Il inclut la propriété suivante :

import type { SchemaContext } from 'astro:content';

export const imageSchema = ({ image }: SchemaContext) =>
    z.object({
        image: image(),
        description: z.string().optional(),
    });

const blog = defineCollection({
  type: 'content',
  schema: ({ image }) => z.object({
    title: z.string(),
    permalink: z.string().optional(),
    image: imageSchema({ image })
  }),
});