portable-text-conversion

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Portable Text Conversion

Portable Text 转换

Convert external content (HTML, Markdown) into Portable Text for Sanity. Three main approaches:

markdownToPortableText
— Convert Markdown directly using
```
@portabletext/markdown
```
(recommended for Markdown)
htmlToBlocks
— Parse HTML into PT blocks using
```
@portabletext/block-tools
```
(for HTML migration)
Manual construction — Build PT blocks directly from any source (APIs, databases, etc.)

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

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

Portable Text Specification

Portable Text 规范

Understand the target format before converting. PT is an array of blocks:

json

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

Key rules:

Every block and span needs
```
_key
```
(unique within the array)
```
_type: "block"
```
is for text blocks; custom types use their own
```
_type
```
```
markDefs
```
holds annotation data;
```
marks
```
on spans reference
```
markDefs[*]._key
```
or are decorator strings
Lists use
```
listItem
```
("bullet" | "number") and
```
level
```
(1, 2, 3...) on regular blocks

在转换前请先了解目标格式。PT是一个块数组：

json

[
  {
    "_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...）属性

Conversion Rules

转换规则

Read the rule file matching your source format:

Markdown → Portable Text:

rules/markdown-to-pt.md

—

@portabletext/markdown

with

markdownToPortableText

(recommended)

HTML → Portable Text:

rules/html-to-pt.md

—

@portabletext/block-tools

with

htmlToBlocks

Manual PT Construction:
```
rules/manual-construction.md
```
— build blocks programmatically from any source

Note:
@sanity/block-tools
is the legacy package name. Always use
@portabletext/block-tools
for new projects. The API is the same.

阅读与你的源格式匹配的规则文件：

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保持不变。