Block Content

Type de ressource : Schéma Sanity (Array/Block)
Fichier source : apps/studio/schemaTypes/blockContent.ts
Statut : Actif
Slice : 2 (Blog)
Version : 1.0

1. Vue d’ensemble (DOC)

1.1. Description

Schéma réutilisable pour le contenu riche en Portable Text. Définit les styles de blocs, les listes, les décorateurs de texte et les annotations (liens). Utilisé par les schémas post et author.

1.2. Objectif

Fournir un format standardisé pour le contenu riche
Permettre l’édition de texte avec formatage (titres, listes, liens)
Supporter l’insertion d’images dans le texte
Être réutilisable dans plusieurs schémas

1.3. Cas d’usage

Rédaction du corps des articles de blog
Rédaction des biographies d’auteurs (version simplifiée inline)
Tout contenu nécessitant du texte riche avec des liens
Support des images insérées dans le texte

1.4. Relations avec d’autres schémas

Relation	Schéma	Type	Description
Utilisé par	`post`	Composition	Le champ body utilise le schéma blockContent
Utilisé par	`author`	Composition (inline)	Le champ bio utilise une version simplifiée inline
Dépend de	Aucun	-	Schéma utilitaire indépendant

2. Structure des données (DOC)

2.1. Styles de blocs disponibles

Style	Valeur	Description
Normal	`normal`	Paragraphe normal
H1	`h1`	Titre de niveau 1
H2	`h2`	Titre de niveau 2
H3	`h3`	Titre de niveau 3
H4	`h4`	Titre de niveau 4
Quote	`blockquote`	Citation

2.2. Listes disponibles

Type	Valeur	Description
Bullet	`bullet`	Liste à puces

2.3. Décorateurs de texte (inline)

Décorateur	Valeur	Description
Strong	`strong`	Texte en gras
Emphasis	`em`	Texte en italique

2.4. Annotations disponibles

Annotation	Nom	Description
URL	`link`	Lien hypertexte avec champ href

2.5. Types de contenus additionnels

Type	Description
`image`	Images pouvant être insérées dans le contenu avec hotspot activé

3. Contrats d’Entrée/Sortie (SPEC)

3.1. Inputs (création/modification)

Champ	Type	Validation	Description
Blocs de texte	`array`	Aucune	Liste des blocs Portable Text
Images	`array`	Aucune	Images insérées dans le contenu

3.2. Outputs (structure du document)

Champ	Type	Description
`_type`	`string`	Type du bloc (`block` ou `image`)
`style`	`string`	Style du bloc (normal, h1, h2, etc.)
`children`	`array`	Contenu textuel du bloc
`markDefs`	`array`	Définitions des annotations (liens)
`hotspot`	`object`	Configuration du recadrage des images

3.3. États du document

Non applicable - blockContent est un schéma de type array, pas un document.

4. Implémentation (CODE)

4.1. Code du schéma

import {defineType, defineArrayMember} from 'sanity'

export default defineType({
  title: 'Block Content',
  name: 'blockContent',
  type: 'array',
  of: [
    defineArrayMember({
      title: 'Block',
      type: 'block',
      styles: [
        {title: 'Normal', value: 'normal'},
        {title: 'H1', value: 'h1'},
        {title: 'H2', value: 'h2'},
        {title: 'H3', value: 'h3'},
        {title: 'H4', value: 'h4'},
        {title: 'Quote', value: 'blockquote'},
      ],
      lists: [{title: 'Bullet', value: 'bullet'}],
      marks: {
        decorators: [
          {title: 'Strong', value: 'strong'},
          {title: 'Emphasis', value: 'em'},
        ],
        annotations: [
          {
            title: 'URL',
            name: 'link',
            type: 'object',
            fields: [
              {
                title: 'URL',
                name: 'href',
                type: 'url',
              },
            ],
          },
        ],
      },
    }),
    defineArrayMember({
      type: 'image',
      options: {hotspot: true},
    }),
  ],
})

4.2. Requêtes GROQ associées

Requête principale (utilisation dans post)

*[_type == "post" && slug.current == $slug][0] {
  _id,
  title,
  body
}

4.3. Types TypeScript (génération automatique)

Non implémenté - sanity-typegen n’est pas configuré dans le projet actuel.

// Types à implémenter manuellement si nécessaire
export type PortableTextBlock = {
  _type: 'block';
  style: 'normal' | 'h1' | 'h2' | 'h3' | 'h4' | 'blockquote';
  children: Array<{
    _type: 'span';
    text: string;
    marks?: string[];
  }>;
  markDefs?: Array<{
    _type: 'link';
    _key: string;
    href: string;
  }>;
};

export type BlockContent = Array<PortableTextBlock | ImageAsset>;

5. Tests attendus (TEST)

5.1. Tests unitaires

Scénario	Description	Résultat attendu
Styles de blocs	Créer un bloc avec style h1	Bloc créé avec style h1
Listes	Créer une liste à puces	Liste créée avec style bullet
Liens	Créer un lien avec annotation	Lien créé avec markDef href
Images	Insérer une image avec hotspot	Image insérée avec configuration hotspot

5.2. Tests d’intégration

Scénario	Dépendances	Description	Résultat attendu
Consommation post	Schéma post + blockContent	Créer un article avec body	Contenu Portable Text fonctionnel
Consommation author	Schéma author + blockContent inline	Créer une bio avec Portable Text	Contenu Portable Text simplifié fonctionnel
Rendu Astro	Route + PortableText component	Rendre le contenu Portable Text	Contenu rendu correctement

5.3. Tests E2E

Scénario	Parcours utilisateur	Description	Résultat attendu
Édition → Rendu	Studio → Build → Site	Éditer un article avec contenu riche	Contenu rendu correctement sur le site
Liens cliquables	Site → Navigation	Cliquer sur un lien dans le contenu	Navigation vers l’URL cible

6. Intégration (INTÉG)

6.1. Intégration avec les composants

Composant	Type	Rôle	Méthode d’intégration
Schéma post	L1	Champ body	Type blockContent
Schéma author	L1	Champ bio (inline)	Version simplifiée inline de blockContent
PortableText component	L2	Rendu du contenu	Utilisation de @portabletext/react (à implémenter)

6.2. Points d’attention

Ce schéma est réutilisable dans plusieurs autres schémas
Les images insérées utilisent le hotspot pour le recadrage
Les liens sont stockés comme annotations dans les markDefs
Portable Text est le format standard de Sanity pour le contenu riche
Nécessite @portabletext/react pour le rendu côté frontend (à implémenter)
Dans author, une version simplifiée inline est utilisée (style normal uniquement, pas de listes)

6.3. Vérification de cohérence

Le schéma ne casse aucun schéma existant
Les styles de blocs sont correctement rendus
Les liens fonctionnent correctement
Les images sont affichées avec le bon recadrage

7. Sécurité

7.1. Mécanismes de sécurité

✅ Les images sont stockées dans Sanity Asset API avec accès contrôlé
✅ Les URLs dans les liens sont validées par Sanity (type url)
✅ Les permissions Sanity sont configurées par rôle

7.2. Validation des entrées

✅ Les URLs des liens sont validées automatiquement par Sanity
✅ Les images sont validées lors de l’upload

8. Performance et limites

8.1. Limites Sanity

Limite	Valeur	Stratégie d’optimisation
Taille du document	16 MB	Éviter les contenus trop volumineux
Profondeur des blocs	Limitée par l’éditeur	Limiter les imbrications

8.2. Optimisations appliquées

✅ Utilisation de Portable Text (format optimisé par Sanity)
✅ Images optimisées via Sanity Asset API

9. Débogage et troubleshooting

9.1. Problèmes courants

Symptôme	Cause probable	Solution
Styles non appliqués	Composant PortableText manquant	Installer @portabletext/react
Liens non cliquables	Annotation mal configurée	Vérifier la structure des markDefs
Images non affichées	Hotspot mal configuré	Vérifier la configuration de l’image

9.2. Commandes de debug

# Extraire le schéma depuis Sanity
npx sanity schema extract

# Générer les types TypeScript (à implémenter)
npx sanity typegen generate

10. Bonnes pratiques

10.1. Architecture

✅ Utiliser @portabletext/react pour le rendu (à implémenter)
✅ Centraliser les composants de rendu Portable Text
✅ Documenter les styles et annotations disponibles

10.2. Code

✅ Utiliser defineArrayMember pour chaque type de contenu
✅ Configurer les styles et annotations appropriés
✅ Activer le hotspot pour les images

10.3. Maintenance

✅ Mettre à jour ce fichier lors de toute modification du schéma
✅ Tester le rendu Portable Text après modification
✅ Vérifier la compatibilité avec @portabletext/react

11. Évolutions et roadmap

11.1. Améliorations planifiées

Implémentation de @portabletext/react pour le rendu
Ajout de styles supplémentaires (ex: h5, h6)
Ajout de types de listes (ex: numbered)
Personnalisation des composants de rendu

11.2. Limitations connues

❌ Portable Text nécessite une librairie de rendu spécifique
❌ Les styles sont limités à ceux configurés dans le schéma
❌ La customisation visuelle nécessite du code custom

12. Ressources liées

Documentation Sanity : Portable Text
Documentation Portable Text : @portabletext/react
Schémas utilisant : post, author
Pages Astro consommatrices : apps/web/src/pages/blog/[...slug].astro
Composants d’affichage : Potentiellement un composant PortableText personnalisé (à implémenter)

13. Historique des modifications

Date	Version	Description	Auteur
2026-09-15	1.0	Création initiale	Devin