Communitygithub.com

khaym/stitch-to-astro

Procédure de création de pages dynamiques avec Astro Content Collections à partir de maquettes Stitch.

Qu'est-ce que stitch-to-astro ?

Ce skill fournit une procédure étape par étape pour créer des pages pilotées par le contenu en utilisant Astro Content Collections (Content Layer API) avec routage dynamique, à partir de maquettes Stitch. Il couvre la définition du schéma, la création des données de contenu au format MDX, la mise en place du routage dynamique avec `[...slug].astro`, et la gestion des images co-localisées. Le skill guide également l'utilisateur dans la création de fichiers de données éditables via YAML frontmatter dans `src/data/`, l'implémentation de composants de section réutilisables dans `src/components/`, et la vérification de la construction avec `npm run build`. Destiné aux développeurs utilisant Astro 5, il automatise le processus allant des spécifications Stitch (fichier `docs/stitch/reference.md`) jusqu'à la génération de pages HTML statiques optimisées.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/khaym/stitch-to-astro/tree/HEAD/.claude/skills/page-procedure

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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.css existe avec les tokens de design (créé par la procédure css-procedure)
  • docs/stitch/reference.md existe (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 dans public/)
  • 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 type ImageMetadata. Utiliser également ImageMetadata dans 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 ; getStaticPaths génère les chemins statiques
  • render() renvoie le corps MDX en tant que composant Content
  • item.data fournit 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 .astro de 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éthodeQuand l'utiliserExemple
<Picture>Images statiques connues à la constructionArrière-plans de hero, images d'entrée
<img>Images échangées dynamiquement par JS clientDiaporamas 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 :

ExigenceImplémentation
Sémantiquerole="dialog" + aria-modal="true" + aria-label
Ouverture/fermetureBasculer l'attribut hidden + transition CSS opacity
Verrouillage du défilementOuvert : document.body.style.overflow = "hidden" / Fermé : restaurer à ""
ClavierEscape pour fermer, touches fléchées pour la navigation
Piège de focusTab/Shift+Tab parcourt les boutons dans la modale
Restauration du focusfocus() sur l'élément déclencheur à la fermeture
Fermeture par fondFermer quand la cible du clic n'est pas un élément interactif
z-indexSupé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

ErreurCauseCorrection
Expected type "string", received "object"YAML a automatiquement converti une valeur (nom de mois → Date, etc.)Mettre la valeur entre guillemets
Could not find imageChemin d'image incorrectVérifier le chemin relatif depuis le fichier MDX
does not match collection schemaChamp manquant ou type incorrect dans le frontmatterVé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.ts a un schéma défini
  • Le frontmatter MDX est conforme au schéma
  • Les images sont dans src/content/ et redimensionnées à ≤2560px
  • [...slug].astro renvoie toutes les entrées de getStaticPaths
  • Les sections avec champs optionnels utilisent un rendu conditionnel
  • npm run build réussit
  • Confirmation visuelle dans le navigateur pour toutes les sections (y compris la largeur mobile)

Skills associés