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
• feishu_doc 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

# Insert from file (appends to document end)
python3 \x3Cskill_dir>/scripts/md2blocks.py \x3Cdoc_token> content.md

# Insert from stdin
echo "| A | B |\
|---|---|\
| 1 | 2 |" | python3 \x3Cskill_dir>/scripts/md2blocks.py \x3Cdoc_token> -

# Insert after a specific block
python3 \x3Cskill_dir>/scripts/md2blocks.py \x3Cdoc_token> content.md --after \x3Cblock_id>

# Replace all content
python3 \x3Cskill_dir>/scripts/md2blocks.py \x3Cdoc_token> content.md --replace

How It Works

1. Calls POST /docx/v1/documents/blocks/convert to convert Markdown → block structures
2. Removes merge_info from table blocks (read-only field that causes insertion errors)
3. 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 \x3Cblock_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