feishu-md2blocks

# 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

```bash
# Insert from file (appends to document end)
python3 <skill_dir>/scripts/md2blocks.py <doc_token> content.md

# Insert from stdin
echo "| A | B |\n|---|---|\n| 1 | 2 |" | python3 <skill_dir>/scripts/md2blocks.py <doc_token> -

# Insert after a specific block
python3 <skill_dir>/scripts/md2blocks.py <doc_token> content.md --after <block_id>

# Replace all content
python3 <skill_dir>/scripts/md2blocks.py <doc_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 <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.bl...