Markdown Import Skill

Core Features

1. Three-stage Concurrent Pipeline: Create blocks sequentially → Process diagrams/tables concurrently → Fallback on failure
2. Mermaid/PlantUML → Feishu Whiteboard: Automatically convert

   mermaid

   /

   plantuml

   /

   puml

   code blocks to Feishu whiteboards
3. Diagram Fault Tolerance: Automatically degrade to code block display for syntax errors, automatically retry for server errors (up to 10 times, 1s interval)
4. Automatic Large Table Splitting: Tables with more than 9 rows are automatically split into multiple tables, each retaining the header
5. Automatic Table Column Width Calculation: Intelligently calculate column widths based on content (distinguish between Chinese and English, minimum 80px, maximum 400px)
6. API Rate Limiting Handling: Automatic retries to avoid 429 errors
7. Concurrency Control: Use independent worker pools for diagrams and tables (default 5 for diagrams, 3 for tables)

Core Concepts

Usage

# 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

1. Validate File
   • Check if the Markdown file exists
   • Preview file content
2. Execute Import
   bash

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

3. Add Permissions
   bash

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

4. Send Notification Notify the user that the document has been created

Update Existing Document

1. Execute Update
   bash

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

2. Notify User

Parameter Description

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)

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

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

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

Callout Highlight Block Examples

> [!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.

Formula Examples

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

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

# 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

*italic*

<u>

$...$

$$...$$

Large-Scale Test Results

• 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

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

Known Mermaid Limitations

{}

{text}

par...and...end

Note over X: Execute in parallel

• 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

• 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