Markdown Import Skill

Create or update Feishu Cloud Docs from local Markdown files. Supports conversion of Mermaid/PlantUML diagrams to Feishu whiteboards and automatic splitting of large tables.

Core Features

Three-stage Concurrent Pipeline: Create blocks sequentially → Process diagrams/tables concurrently → Fallback on failure
Mermaid/PlantUML → Feishu Whiteboard: Automatically convert
```
mermaid
```
/
```
plantuml
```
/
```
puml
```
code blocks to Feishu whiteboards
Diagram Fault Tolerance: Automatically degrade to code block display for syntax errors, automatically retry for server errors (up to 10 times, 1s interval)
Automatic Large Table Splitting: Tables with more than 9 rows are automatically split into multiple tables, each retaining the header
Automatic Table Column Width Calculation: Intelligently calculate column widths based on content (distinguish between Chinese and English, minimum 80px, maximum 400px)
API Rate Limiting Handling: Automatic retries to avoid 429 errors
Concurrency Control: Use independent worker pools for diagrams and tables (default 5 for diagrams, 3 for tables)

Core Concepts

Markdown as Intermediate State: Convert between local documents and Feishu Cloud Docs using Markdown format.

Usage

bash

# Create new document
/feishu-import ./document.md --title "Document Title"

# Update existing document
/feishu-import ./document.md --document-id <existing_doc_id>

# Upload local images
/feishu-import ./document.md --title "Document with Images" --upload-images

Execution Flow

Create New Document

Validate File
- Check if the Markdown file exists
- Preview file content

Execute Import

bash

feishu-cli doc import <file.md> --title "<title>" [--upload-images]

Add Permissions

bash

feishu-cli perm add <document_id> --doc-type docx --member-type email --member-id user@example.com --perm full_access

Send Notification Notify the user that the document has been created

Update Existing Document

Execute Update

bash

feishu-cli doc import <file.md> --document-id <doc_id> [--upload-images]

Notify User

Parameter Description

Parameter	Description	Default Value
markdown_file	Path to Markdown file	Required
--title	Title of new document	File name
--document-id	Update existing document	Create new document
--upload-images	Upload local images	No
--diagram-workers	Number of concurrent imports for diagrams (Mermaid/PlantUML)	5
--table-workers	Number of concurrent table fill operations	3
--diagram-retries	Maximum number of retries for diagrams	10
--verbose	Show detailed progress information	No

Supported Markdown Syntax

Headings (# ~ ######)
Paragraph text
Unordered/ordered lists (supports infinite depth nesting, mixed nesting)
Task lists (- [ ] / - [x])
Code blocks (with language identifiers)
Mermaid/PlantUML diagrams → Automatically converted to Feishu whiteboards
Blockquotes (supports nested quotes, automatically converted to QuoteContainer)
Callout highlight blocks (
```
> [!NOTE]
```
,
```
> [!WARNING]
```
, etc., 6 types)
Horizontal rules
Images (create placeholder blocks; Feishu Open API does not support inserting actual images yet; inline images are converted to links or text placeholders)
Tables (automatically split if more than 9 rows)
Bold, italic, strikethrough, inline code, underline (
```
<u>text</u>
```
)
Links
Inline formulas (
```
$E = mc^2$
```
, supports multiple formulas in one paragraph)
Block formulas (
```
$$formula$$
```
or standalone line
```
$formula$
```
)

Diagram Examples (Mermaid Recommended)

markdown

```mermaid
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Process]
    B -->|No| D[End]
```

markdown

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi
@enduml
```

Supported Mermaid diagram types (all verified):

✅ flowchart (supports subgraph nesting)
✅ sequenceDiagram
✅ classDiagram
✅ stateDiagram-v2
✅ erDiagram
✅ gantt
✅ pie
✅ mindmap

Callout Highlight Block Examples

markdown

> [!NOTE]
> This is a note message.

> [!WARNING]
> This is a warning message.

> [!TIP]
> This is a tip message.

> [!CAUTION]
> This is a caution message.

> [!IMPORTANT]
> This is an important message.

> [!SUCCESS]
> This is a success message.

Callouts support inner blocks (paragraphs, lists, etc.), which are automatically created as child blocks of the Callout.

Background Color Mapping:

Type	Background Color
NOTE/INFO	Blue (6)
WARNING	Red (2)
TIP	Yellow (4)
CAUTION	Orange (3)
IMPORTANT	Purple (7)
SUCCESS	Green (5)

Formula Examples

markdown

Inline formula: Einstein's mass-energy equation $E = mc^2$ is the most famous formula.

Block formula (standalone line):
$\int_{0}^{\infty} e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$

Multiple
```
$...$
```
formulas are supported in a single paragraph for inline formulas
Block formulas are created as Equation elements within Text blocks in Feishu
Formula content retains the original LaTeX text

Underline Example

markdown

This text contains <u>underline</u> styling.

Output Format

Document imported successfully!
  Document ID: <document_id>
  Document Link: https://feishu.cn/docx/<document_id>
  Number of Imported Blocks: 25

Examples

bash

# Create new document
/feishu-import ./meeting-notes.md --title "Meeting Minutes"

# Update existing document
/feishu-import ./updated-spec.md --document-id <document_id>

# Import with images (creates placeholder blocks; Open API does not support inserting actual images yet)
/feishu-import ./blog-post.md --title "Blog Post" --upload-images

Verified Features

The following import features have been tested and verified:

Markdown Syntax	Import Status	Description
Headings (# ~ ######)	✅ Normal
Paragraph text	✅ Normal
Unordered lists (with nesting)	✅ Normal	Supports infinite depth nesting
Ordered lists (with nesting)	✅ Normal	Supports infinite depth nesting
Mixed nested lists	✅ Normal	Mixed ordered/unordered nesting
Task lists	✅ Normal
Code blocks	✅ Normal
Mermaid/PlantUML diagrams	✅ Normal	Automatically converted to Feishu whiteboards
Blockquotes	✅ Normal	Converted to QuoteContainer, supports nested quotes
Callout highlight blocks	✅ Normal	6 types, supports child blocks
Horizontal rules	✅ Normal
Bold/ `italic` /~~strikethrough~~	✅ Normal
Underline ( `<u>` )	✅ Normal
Inline code	✅ Normal
Inline formulas ( $...$ )	✅ Normal	Supports multiple formulas in one paragraph
Block formulas ( `$$...$$` )	✅ Normal	Created as Equation elements within Text blocks
Tables	✅ Normal	Automatically split if more than 9 rows
Links	✅ Normal
Images	✅ Placeholder block	Open API does not support inserting actual images; creates empty Image blocks, users can manually add images via web interface
Inline images	✅ Linked	Network URLs converted to clickable links, local paths converted to text placeholders

Large-Scale Test Results

Successfully imported large documents verified:

10,000+ lines of Markdown ✓
127 Mermaid diagrams → All successfully converted to Feishu whiteboards ✓
170+ tables (including large table splitting, automatic column width calculation) → All successful ✓
8 diagram types → flowchart/sequenceDiagram/classDiagram/stateDiagram/erDiagram/gantt/pie/mindmap all successful ✓
88 Mermaid diagrams tested individually → 82/88 successful, 6 failed (3 server transient errors + 2 curly brace syntax issues + 1 extraction exception)

Three-Stage Concurrent Pipeline Architecture

Stage 1 (Sequential): Create all document blocks, collect tasks for diagrams (Mermaid/PlantUML) and tables
Stage 2 (Concurrent): Use worker pools to process diagram imports and table filling concurrently
Stage 3 (Reverse Order): Process failed diagrams → Delete empty whiteboard blocks, insert code blocks as fallback display

Known Mermaid Limitations

Limitation	Description	Handling Method
`{}` curly braces	Mermaid parser recognizes `{text}` as diamond nodes	Automatically degrade to code block
`par...and...end`	Feishu parser does not support par parallel syntax at all	Replace with `Note over X: Execute in parallel`
Excessive rendering complexity combination	No single factor triggers it, but combination of 10+ participants + 2+ alt blocks + 30+ long message labels leads to server 500 error	Degrade to code block after retries
Server transient errors	Occasional HTTP 500 (caused by concurrent pressure)	Automatic retries (up to 10 times, 1s interval)
Parse error not retried	Directly degrade for syntax errors	Automatically degrade to code block

Rendering Complexity Safety Threshold (measured via binary search):

Participants ≤8 or alt ≤1 or short message labels → Safe
10 participants + 2 alt blocks + 30 long message labels → Exceeds threshold
Recommendation: Keep participants ≤8, alt ≤1, and message labels short for sequenceDiagram

Technical Notes

Diagrams are imported via Feishu Whiteboard API:

API endpoint:

/open-apis/board/v1/whiteboards/{id}/nodes/plantuml

```
syntax_type=1
```
indicates PlantUML syntax,
```
syntax_type=2
```
indicates Mermaid syntax
```
diagram_type
```
uses integers (0=auto, 6=flowchart, etc.)
Retry strategy: Fixed 1s interval, no retries for Parse error and Invalid request parameter
Failure fallback: Delete empty whiteboard blocks, insert code blocks at original position
Supported code block identifiers:
```
```mermaid
```
,
```
```plantuml
```
,
```
```puml
```

feishu-cli-import

NPX Install

Tags

SKILL.md Content (Chinese)

Markdown Import Skill

Core Features

Core Concepts

Usage

Execution Flow

Create New Document

Update Existing Document

Parameter Description

Supported Markdown Syntax

Diagram Examples (Mermaid Recommended)

Callout Highlight Block Examples

Formula Examples

Underline Example

Output Format

Examples

Verified Features

Large-Scale Test Results

Three-Stage Concurrent Pipeline Architecture

Known Mermaid Limitations

Technical Notes