Block Content

Block Content

Documentation technique

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éma1/2

4.1. Code du schéma2/2

apps/studio/schemaTypes/blockContent.ts

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

Switch to normal mode

ContentsSpeaker viewToggle fullscreenExport as PDF

Contents

Close

Block Content

1. 1. Vue d’ensemble (DOC)3
2. 1.1. Description4
3. 1.2. Objectif5
4. 1.3. Cas d’usage6
5. 1.4. Relations avec d’autres schémas7
6. 2. Structure des données (DOC)8
7. 2.1. Styles de blocs disponibles9
8. 2.2. Listes disponibles10
9. 2.3. Décorateurs de texte (inline)11
10. 2.4. Annotations disponibles12
11. 2.5. Types de contenus additionnels13
12. 3. Contrats d’Entrée/Sortie (SPEC)14
13. 3.1. Inputs (création/modification)15
14. 3.2. Outputs (structure du document)16
15. 3.3. États du document17
16. 4. Implémentation (CODE)18
17. 4.1. Code du schéma19
18. 4.2. Requêtes GROQ associées21
19. 4.3. Types TypeScript (génération automatique)22
20. 5. Tests attendus (TEST)23
21. 5.1. Tests unitaires24
22. 5.2. Tests d’intégration25
23. 5.3. Tests E2E26
24. 6. Intégration (INTÉG)27
25. 6.1. Intégration avec les composants28
26. 6.2. Points d’attention29
27. 6.3. Vérification de cohérence30
28. 7. Sécurité31
29. 7.1. Mécanismes de sécurité32
30. 7.2. Validation des entrées33
31. 8. Performance et limites34
32. 8.1. Limites Sanity35
33. 8.2. Optimisations appliquées36
34. 9. Débogage et troubleshooting37
35. 9.1. Problèmes courants38
36. 9.2. Commandes de debug39
37. 10. Bonnes pratiques40
38. 10.1. Architecture41
39. 10.2. Code42
40. 10.3. Maintenance43
41. 11. Évolutions et roadmap44
42. 11.1. Améliorations planifiées45
43. 11.2. Limitations connues46
44. 12. Ressources liées47
45. 13. Historique des modifications48