Conversion en Portable Text

Convertir du contenu externe (HTML, Markdown) en Portable Text pour Sanity. Trois approches principales :

1. markdownToPortableText — Convertir du Markdown directement avec @portabletext/markdown (recommandé pour le Markdown)
2. htmlToBlocks — Analyser du HTML en blocs PT avec @portabletext/block-tools (pour la migration HTML)
3. Construction manuelle — Construire les blocs PT directement à partir de n'importe quelle source (APIs, bases de données, etc.)

Spécification Portable Text

Comprendre le format cible avant de convertir. PT est un tableau de blocs :

[
  {
    "_type": "block",
    "_key": "abc123",
    "style": "normal",
    "children": [
      {"_type": "span", "_key": "def456", "text": "Hello ", "marks": []},
      {"_type": "span", "_key": "ghi789", "text": "world", "marks": ["strong"]}
    ],
    "markDefs": []
  },
  {
    "_type": "block",
    "_key": "jkl012",
    "style": "h2",
    "children": [
      {"_type": "span", "_key": "mno345", "text": "A heading", "marks": []}
    ],
    "markDefs": []
  },
  {
    "_type": "image",
    "_key": "pqr678",
    "asset": {"_type": "reference", "_ref": "image-abc-200x200-png"}
  }
]

Règles clés :

• Chaque bloc et span a besoin d'une _key (unique dans le tableau)
• _type: "block" est pour les blocs de texte ; les types personnalisés utilisent leur propre _type
• markDefs contient les données d'annotation ; marks sur les spans référencent markDefs[*]._key ou sont des chaînes décorateurs
• Les listes utilisent listItem ("bullet" | "number") et level (1, 2, 3...) sur les blocs réguliers

Règles de conversion

Consulter le fichier de règles correspondant à votre format source :

• Markdown → Portable Text : rules/markdown-to-pt.md — @portabletext/markdown avec markdownToPortableText (recommandé)
• HTML → Portable Text : rules/html-to-pt.md — @portabletext/block-tools avec htmlToBlocks
• Construction manuelle PT : rules/manual-construction.md — construire les blocs par programme à partir de n'importe quelle source

Note : @sanity/block-tools est le nom du package hérité. Toujours utiliser @portabletext/block-tools pour les nouveaux projets. L'API est la même.