feishu-md2blocks_skill

Overview

This skill inserts rich Markdown content—including tables, code blocks, and nested lists—into Feishu documents by converting Markdown to Feishu block structures and using the descendant insert API. It is designed for cases where simple write/append operations fail with complex content or when you need to insert at a specific position inside an existing document. The tool handles table quirks that commonly cause insertion errors.

How this skill works

The script converts Markdown to Feishu blocks via the block convert endpoint, strips read-only table fields that cause failures, and posts the resulting blocks to the document descendant API so nested structures are preserved. It supports position control by computing block indices and placing the index in the request body (not the URL), and it splits large inserts to respect the block-count limit.

When to use it

• You need to insert Markdown (tables, code blocks, nested lists) into an existing Feishu doc without replacing the whole document.
• feishu_doc write/append fails when tables or complex nested content are involved.
• You must insert content after a particular block or at a precise position inside a document.
• You want reliable conversion of Markdown tables and preserved nested structures.
• You need to append Markdown content programmatically while avoiding merge_info errors in table blocks.

Best practices

• Ensure the Feishu app has docx:document.block:convert permission before running the script.
• When inserting very large documents, split into chunks under 1000 blocks per call to avoid limits.
• Use the --after <block_id> flag to target insertion points; the script calculates the correct index and sends it in the request body.
• Pre-upload images separately and patch block references, since Markdown image links are not auto-uploaded.
• Respect document edit rate limits (about 3 ops/sec per document) to avoid throttling.

Example use cases

• Append a Markdown-formatted report with complex tables and code snippets to a shared Feishu doc without overwriting existing content.
• Insert a generated changelog or release notes after a specific header block in a long document.
• Migrate Markdown documentation into a Feishu handbook while preserving nested lists and table layouts.
• Programmatically insert Markdown renderings from CI jobs into a daily operations document at a precise location.