Feishu Markdown to Blocks
Insert Markdown content—including tables—into Feishu documents via the block convert + descendant API.
When to Use
- -
feishu_doc write replaces the entire document; use this to insert content at a position - INLINECODE2
create_table_with_values has limitations for larger tables - You need to insert tables, code blocks, or complex nested content into an existing doc
Usage
CODEBLOCK0
How It Works
- 1. Calls
POST /docx/v1/documents/blocks/convert to convert Markdown → block structures - Removes
merge_info from table blocks (read-only field that causes insertion errors) - Calls
POST /docx/v1/documents/{doc}/blocks/{parent}/descendant to insert blocks
The descendant API handles nested structures (tables with cells containing text) that the simpler /children API cannot.
Position Control
The --after <block_id> option inserts content right after the specified block. The script finds the block's index automatically.
Key detail: The /descendant API's index parameter must be in the request body, not as a URL query parameter. Passing ?index=N in the URL is silently ignored (content appends to end). The script handles this correctly.
Supported Markdown
Text, headings (h1-h9), bullet lists, ordered lists, code blocks, quotes, tables, todo items, dividers.
Limitations
- - Images in Markdown are not automatically uploaded; they require separate upload + patch steps
- Max 1000 blocks per insert call; split large documents if needed
- Requires
docx:document.block:convert permission on the Feishu app - Document edit rate limit: 3 ops/sec per document
Reference
For complete block-level API reference, see the feishu-block-ops skill which covers:
- - All block APIs (create/read/update/delete/batch)
- Block type reference, text element types
- Table operation patterns (batch edit, merge cells)
- Common patterns and gotchas
飞书 Markdown 转块
通过块转换 + 后代 API，将 Markdown 内容（包括表格）插入飞书文档。
使用场景
- - feishudoc 的 write 操作会替换整个文档；使用此工具可在指定位置插入内容
- feishudoc 的 createtablewith_values 操作对较大表格存在限制
- 需要向现有文档中插入表格、代码块或复杂嵌套内容
使用方法
bash
从文件插入（追加到文档末尾）
python3
dir>/scripts/md2blocks.py token> content.md
从标准输入插入
echo | A | B |\n|---|---|\n| 1 | 2 | | python3 dir>/scripts/md2blocks.py token> -
在指定块后插入
python3 dir>/scripts/md2blocks.py token> content.md --after
替换所有内容
python3 dir>/scripts/md2blocks.py token> content.md --replace
工作原理
- 1. 调用 POST /docx/v1/documents/blocks/convert 将 Markdown 转换为块结构
- 从表格块中移除 merge_info（只读字段，会导致插入错误）
- 调用 POST /docx/v1/documents/{doc}/blocks/{parent}/descendant 插入块
后代 API 能够处理嵌套结构（包含文本单元格的表格），这是更简单的 /children API 无法实现的。
位置控制
--after 选项可在指定块后插入内容。脚本会自动查找该块的索引。
关键细节： /descendant API 的 index 参数必须放在请求体中，而不是作为 URL 查询参数。在 URL 中传递 ?index=N 会被静默忽略（内容会追加到末尾）。脚本已正确处理此问题。
支持的 Markdown
文本、标题（h1-h9）、无序列表、有序列表、代码块、引用、表格、待办事项、分隔线。
限制
- - Markdown 中的图片不会自动上传，需要单独执行上传 + 补丁操作
- 每次插入调用最多支持 1000 个块；大文档需要拆分
- 需要在飞书应用中拥有 docx:document:block:convert 权限
- 文档编辑速率限制：每个文档每秒 3 次操作
参考
完整的块级 API 参考，请参见 feishu-block-ops 技能，其中涵盖：
- - 所有块 API（创建/读取/更新/删除/批量操作）
- 块类型参考、文本元素类型
- 表格操作模式（批量编辑、合并单元格）
- 常见模式与注意事项
