Procédure de Page de Contenu
Procédure pas à pas pour créer des pages de contenu dynamique en utilisant Astro Content Collections (Content Layer API) avec routage dynamique.
Prérequis
src/styles/global.cssexiste avec les tokens de design (créé par la procédure css-procedure)docs/stitch/reference.mdexiste (informations de champs issues des écrans Stitch)
Entrée / Sortie
[Entrée] [Sortie]
docs/stitch/reference.md ──┐
(infos des champs d'écran) │
notes progress.md ──────────┼──→ src/content/config.ts (schéma)
(Structure de section, │ src/content/<collection>/<slug>/index.mdx (données)
décisions de conception) │ src/pages/<collection>/[...slug].astro (routage)
│ src/components/*.astro (composants de section)
Étapes
Étape 1 : Définition du Schéma (src/content/config.ts)
Astro 5 Content Layer API utilise le loader glob.
1-1. Définir la Collection
import { defineCollection, z } from "astro:content";
import { glob } from "astro/loaders";
const maCollection = defineCollection({
loader: glob({ pattern: "**/index.mdx", base: "./src/content/ma-collection" }),
schema: ({ image }) =>
z.object({
title: z.string(),
// ... définir les champs
heroImage: image(), // Utiliser le helper image() pour les images
}),
});
export const collections = { maCollection };
1-2. Règles de Conception du Schéma
- Commencer minimal, étendre progressivement. Ne définir que les champs nécessaires au rendu de la page courante ; en ajouter d'autres lors de l'implémentation des composants.
- Utiliser le helper
image()pour les champs d'image afin de permettre la validation et l'optimisation des chemins à la construction. - Utiliser
.optional()pour les champs qui ne sont pas requis dans chaque entrée. - Utiliser des tableaux optionnels pour les données de section afin de contrôler la visibilité des sections par page :
// Schéma moments: z.array(z.object({ title: z.string(), ... })).optional()<!-- Modèle de page : rendu conditionnel --> {data.moments && <MomentsSection moments={data.moments} />}
1-3. Pièges du YAML Frontmatter
- Les noms de mois (Mars, Mai, etc.) et Oui/Non sont automatiquement convertis par YAML. Mettez-les entre guillemets s'ils doivent être des chaînes :
date: "Mars" - Les chemins d'image sont relatifs au fichier MDX :
heroImage: ./hero.jpg
Étape 2 : Créer les Données de Contenu
2-1. Structure de Répertoire
src/content/<collection>/<slug>/
├── index.mdx # frontmatter + corps MDX
├── hero.jpg # Images co-localisées avec le contenu
└── ...
2-2. Structure du Fichier MDX
---
title: "Titre de la Page"
heroImage: ./hero.jpg
description: "Texte de description"
---
## Corps MDX
Le contenu du corps est récupéré via `render()` et rendu en tant que `<Content />`.
2-3. Gestion des Images
- Stocker les images dans
src/content/co-localisées avec leur contenu (pas danspublic/) - Redimensionner les images de plus de 2560px avant de les commiter
- En utilisant le helper
image()dans le schéma, les chemins d'image dans le frontmatter se résolvent en typeImageMetadata. Utiliser égalementImageMetadatadans les Props des composants
Étape 3 : Page de Routage Dynamique
Crer src/pages/<collection>/[...slug].astro :
---
import type { GetStaticPaths } from "astro";
import { getCollection, render } from "astro:content";
export const getStaticPaths = (async () => {
const items = await getCollection("maCollection");
return items.map((item) => ({
params: { slug: item.id },
props: { item },
}));
}) satisfies GetStaticPaths;
const { item } = Astro.props;
const { Content } = await render(item);
---
Points Clés
getCollection()récupère toutes les entrées ;getStaticPathsgénère les chemins statiquesrender()renvoie le corps MDX en tant que composantContentitem.datafournit un accès typé sécurisé aux champs du frontmatter- Rendu conditionnel pour les champs optionnels :
{data.field && <Component ... />}
Étape 4 : Fichiers de Données de Page (src/data/<page>.md)
Le contenu modifiable par l'utilisateur (texte, libellés, URLs) pour chaque page doit être défini dans des fichiers Markdown avec frontmatter YAML sous src/data/. Cela maintient un format cohérent avec les Content Collections et facilite la recherche et l'édition du contenu par l'utilisateur.
Remarque : Le répertoire
src/data/n'est pas créé par le skill de structure. Créez-le dans cette étape.
4-1. Créer un fichier de données pour chaque page
src/data/
├── index.md # Contenu de la page Travaux (Accueil)
├── about.md # Contenu de la page À propos
└── skills.md # Contenu de la page Compétences
4-2. Définir le contenu modifiable en tant que frontmatter YAML
---
# ==============================
# Contenu de la page Travaux
# Modifiez ce fichier pour personnaliser votre page.
# ==============================
hero:
headingPrefix: "Bonjour, je suis"
highlightedText: "Développeur Web."
description: "Je construis des applications évolutives et centrées sur l'utilisateur..."
badgeText: "Disponible pour de nouveaux projets"
cta:
heading: "Prêt à construire quelque chose ensemble ?"
description: "Je suis actuellement ouvert aux opportunités freelance..."
buttons:
- label: "Me Contacter"
href: "mailto:[email protected]"
variant: "primary"
- label: "Télécharger CV"
href: "#"
variant: "secondary"
---
- Ne mettre que le texte modifiable par l'utilisateur dans le YAML (chaînes, libellés, URLs, tableaux de texte)
- Conserver les données non modifiables (chemins d'icônes SVG, etc.) en tant que constantes TypeScript dans le fichier
.astrode la page
4-3. Importer les données dans la page
Utiliser import.meta.glob() pour charger le frontmatter :
---
const content = Object.values(
import.meta.glob("../data/index.md", { eager: true })
)[0] as { frontmatter: Record<string, unknown> };
const { hero, cta } = content.frontmatter;
---
Étape 5 : Implémentation des Composants de Section
Créer chaque section (hero, moments, etc.) sous forme de composant indépendant dans src/components/.
Suivre les règles de structure des composants et de CSS du guide de développement.
Affichage des Images : <Picture> vs <img>
| Méthode | Quand l'utiliser | Exemple |
|---|---|---|
<Picture> | Images statiques connues à la construction | Arrière-plans de hero, images d'entrée |
<img> | Images échangées dynamiquement par JS client | Diaporamas de galerie modale |
<Picture> étant rendu à la construction, il ne peut pas être utilisé quand src est échangé par JS client.
JavaScript Côté Client
Les balises <script> dans les composants Astro s'exécutent en tant que JS client. Les fonctionnalités interactives peuvent être construites sans frameworks (React, etc.).
Schéma de passage de données : Utiliser les attributs data-* pour transmettre les données du frontmatter au JS client. <script> ne peut pas référencer directement les variables du frontmatter.
Accessibilité : Modale / Superposition
Liste de contrôle pour l'implémentation d'une boîte de dialogue modale :
| Exigence | Implémentation |
|---|---|
| Sémantique | role="dialog" + aria-modal="true" + aria-label |
| Ouverture/fermeture | Basculer l'attribut hidden + transition CSS opacity |
| Verrouillage du défilement | Ouvert : document.body.style.overflow = "hidden" / Fermé : restaurer à "" |
| Clavier | Escape pour fermer, touches fléchées pour la navigation |
| Piège de focus | Tab/Shift+Tab parcourt les boutons dans la modale |
| Restauration du focus | focus() sur l'élément déclencheur à la fermeture |
| Fermeture par fond | Fermer quand la cible du clic n'est pas un élément interactif |
| z-index | Supérieur aux éléments fixes existants (ex. : header 50 → modale 60) |
Étape 6 : Vérification de la Construction
npm run build
Les erreurs de validation du schéma Content Collections apparaissent à la construction avec des messages clairs.
Erreurs Courantes
| Erreur | Cause | Correction |
|---|---|---|
Expected type "string", received "object" | YAML a automatiquement converti une valeur (nom de mois → Date, etc.) | Mettre la valeur entre guillemets |
Could not find image | Chemin d'image incorrect | Vérifier le chemin relatif depuis le fichier MDX |
does not match collection schema | Champ manquant ou type incorrect dans le frontmatter | Vérifier le schéma dans config.ts |
Étape 7 : Vérification du Serveur de Développement
npm run dev
- Les modifications de schéma peuvent nécessiter un redémarrage du serveur de développement (vidage du cache de contenu)
- Si des erreurs persistent après le redémarrage, supprimer le répertoire
.astro/et redémarrer
Liste de Contrôle
-
src/content/config.tsa un schéma défini - Le frontmatter MDX est conforme au schéma
- Les images sont dans
src/content/et redimensionnées à ≤2560px -
[...slug].astrorenvoie toutes les entrées degetStaticPaths - Les sections avec champs optionnels utilisent un rendu conditionnel
-
npm run buildréussit - Confirmation visuelle dans le navigateur pour toutes les sections (y compris la largeur mobile)