portable-text-conversion

便携文本转换

将外部内容（HTML、Markdown）转换为 Sanity 的 Portable Text。主要有三种方式：

1. markdownToPortableText — 使用 @portabletext/markdown 直接转换 Markdown（推荐用于 Markdown）
2. htmlToBlocks — 使用 @portabletext/block-tools 将 HTML 解析为 PT 块（用于 HTML 迁移）
3. 手动构建 — 直接从任意来源（API、数据库等）构建 PT 块

Portable Text 规范

转换前先了解目标格式。PT 是一个由块组成的数组：

[
  {
    "_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"}
  }
]

主要规则：

• 每个块和 span 都需要 _key（在数组中唯一）
• _type: "block" 用于文本块；自定义类型使用各自的 _type
• markDefs 保存注释数据；span 上的 marks 引用 markDefs[*]._key 或使用装饰器字符串
• 列表使用常规块上的 listItem（"bullet" | "number"）和 level（1、2、3……）

转换规则

根据来源格式阅读对应的规则文件：

• Markdown → Portable Text：rules/markdown-to-pt.md — 使用 @portabletext/markdown 和 markdownToPortableText（推荐）
• HTML → Portable Text：rules/html-to-pt.md — 使用 @portabletext/block-tools 和 htmlToBlocks
• 手动构建 PT：rules/manual-construction.md — 以编程方式从任意来源构建块

注意： @sanity/block-tools 是旧版包名。新项目请始终使用 @portabletext/block-tools。API 相同。