Feishu Document Creation Specification Guide

1. Overview

This skill is a reference specification for other Feishu document skills and cannot be called directly. It integrates verification experience from the following sources:

feishu-cli

project code implementation (

converter/

client/board.go

cmd/import_markdown.go

)

Actual test data from

feishu-cli-write

feishu-cli-import

feishu-cli-plantuml

skills

Large-scale import test: verification results of 10,000+ lines / 127 charts / 170+ tables

Applicable Scenario: Refer to this specification to ensure compatibility when generating Markdown documents to be imported into Feishu.

2. Full Markdown Syntax Reference

Supported Syntax and Block Type Mapping

Markdown Syntax	Block Type	Feishu Block Name	Description
`# Heading` ~ `###### Heading`	3-8	Heading1-6	Up to 6 levels (H7-H9 will be downgraded to bold paragraphs when exported)
Normal paragraph	2	Text	Plain text
`- Unordered list`	12	Bullet	Supports unlimited depth nesting
`1. Ordered list`	13	Ordered	Supports unlimited depth nesting
`- [x]` / `- [ ]`	17	Todo	Task list
```lang	14	Code	Code block (supports language identifiers)
`> Quote`	34	QuoteContainer	Quote container (uses QuoteContainer for import)
`> [!NOTE]`	19	Callout	Highlight block (6 types, see Section 5)
`---`	22	Divider	Divider line
Markdown table	31	Table	Automatically split when exceeding 9 rows (see Section 6)
`![alt](url)`	27	Image	Placeholder block (see Section 7)
```mermaid	21→43	Diagram→Board	Automatically converted to Feishu board (see Section 3)
```plantuml / ```puml	21→43	Diagram→Board	Automatically converted to Feishu board (see Section 4)
`$$Formula$$`	16	Equation	Block-level formula (downgraded to inline Equation)
$Formula$	—	InlineEquation	Inline formula

Inline Styles

Markdown	Effect	Description
`Bold`	Bold	Bold TextStyle
`Italic`	Italic	Italic TextStyle
`Inline code`	`Code`	InlineCode TextStyle
`~~Strikethrough~~`	~~Strikethrough~~	Strikethrough TextStyle
`<u>Underline</u>`	Underline	Underline TextStyle
`[Text](url)`	Link	Link TextElement
`==Highlight==`	Highlight	Highlight (requires option enabled)

Nested List Example

markdown

- Level 1 unordered
  - Level 2 unordered
    - Level 3 unordered
      1. Level 4 ordered
      2. Level 4 ordered
    - Level 3 unordered
  - Level 2 unordered

Unordered/ordered lists support unlimited depth nesting and mixed nesting, and indentation levels are automatically preserved during import.

3. Feishu Mermaid Syntax Specification

This is the most important section. Mermaid chart import into Feishu has strict syntax restrictions; non-compliance will cause rendering failure.

8 Supported Chart Types

Type	Declaration	Feishu diagram_type	Description
Flowchart	`flowchart TD` / `flowchart LR`	6 (flowchart)	Supports subgraph
Sequence Diagram	`sequenceDiagram`	2 (sequence)	Strictest complexity restrictions
Class Diagram	`classDiagram`	4 (class)
State Diagram	`stateDiagram-v2`	0 (auto)	Must use v2
ER Diagram	`erDiagram`	5 (er)
Gantt Chart	`gantt`	0 (auto)
Pie Chart	`pie`	0 (auto)
Mind Map	`mindmap`	1 (mindmap)

6 Mandatory Rules

Rule 1: Forbid using curly braces

{}

in labels

Curly braces will be recognized as diamond (decision) nodes by the Mermaid parser, causing syntax errors. This rule applies to flowchart node labels;

{}

in the syntax structure of erDiagram/classDiagram is not restricted.

markdown

<!-- ❌ Error -->
flowchart TD
    A["{name: value}"]

<!-- ✅ Correct -->
flowchart TD
    A["name: value"]

Alternative: Remove curly braces, or replace with parentheses/square brackets.

Rule 2: Forbid using

par...and...end

parallel syntax

Feishu board does not support

par

syntax at all (error code 2891001).

markdown

<!-- ❌ Error -->
sequenceDiagram
    par
        A->>B: Request 1
    and
        A->>C: Request 2
    end

<!-- ✅ Correct: Replace with Note -->
sequenceDiagram
    Note over A,C: Parallel processing
    A->>B: Request 1
    A->>C: Request 2

Rule 3: Avoid colons in square brackets

Colons in square brackets

[text:xxx]

may cause parsing ambiguity.

markdown

<!-- ❌ May cause error -->
flowchart TD
    A[Type:string]

<!-- ✅ Correct -->
flowchart TD
    A["Type: string"]

Fix: Add double quotes to labels containing colons.

Rule 4: Note scope restriction

Note over

can span at most 2 adjacent participants.

markdown

<!-- ❌ Error: Too many participants spanned -->
sequenceDiagram
    Note over A,D: Description

<!-- ✅ Correct -->
sequenceDiagram
    Note over A,B: Description

Rule 5: SequenceDiagram Complexity Threshold

Dimension	Safe Threshold	Risk of Exceeding
Number of participants	≤ 8	Exceeding 10 + other factors → Failure
alt/opt nesting	≤ 1 layer	Exceeding 2 layers → Increased failure risk
Message label length	Short (≤ 30 characters)	Long labels + multiple participants → Failure
Total number of messages	≤ 30	Need to evaluate with other factors

Exceeding Combination (guaranteed to fail in tests): 10+ participants + 2+ alt layers + 30+ long message labels

Recommendation: Split into multiple small diagrams when exceeding the safe threshold.

Rule 6: Avoid overly complex nested structures

Complex structures such as multi-layer subgraph nesting and a large number of conditional branches will increase the probability of rendering failure. Keep diagrams concise.

Pre-Generation Checklist

Before generating Mermaid code blocks, check each item:

Is the chart type among the 8 supported types?
Are there curly braces
```
{}
```
in the labels? → Remove or replace
Is
```
par...and...end
```
used? → Replace with
```
Note over
```
Are there colons in square bracket labels? → Add double quotes
Does sequenceDiagram have ≤ 8 participants?
Does sequenceDiagram have ≤ 1 layer of alt nesting?
Is the overall complexity controllable? → Consider splitting

Detailed templates for 8 chart types and more positive/negative examples can be found in
references/mermaid-spec.md
.

4. PlantUML Safe Subset

Global Rules

Wrap with

@startuml

@enduml

(use

@startmindmap

@endmindmap

for mind maps)

Do not use leading indentation (Feishu board treats indented lines as independent lines)
Avoid style directives such as
```
skinparam
```
,
```
!define
```
, color, font, alignment control
Avoid direction control directives (e.g.,
```
left to right direction
```
is unreliable in some scenarios)

Notes by Chart Type

Chart Type	Safe Syntax	Forbidden
Activity Diagram	`start/stop` , `:Action;` , `if/then/else/endif` , `repeat` , `fork`	Avoid deep nesting
Sequence Diagram	`participant` , `->` / `-->` 、 `activate/deactivate` , `note` , `alt/opt/loop`	Avoid style directives
Class Diagram	`class` , `interface` , `package` , relationship arrows	Avoid visibility markers (+ - # ~)
Use Case Diagram	`actor` , `(Use Case)` , `<<include>>` / `<<extend>>`	Avoid complex layouts
Component Diagram	`[Component]` , `package/node/cloud/database`	Avoid ArchiMate sprite
ER Diagram	`entity` , relationship arrows	Different from Mermaid ER syntax
Mind Map	`@startmindmap` , `* / +` level markers	Must use dedicated wrapping tags

Mermaid vs PlantUML Selection Strategy

Scenario	Recommendation	Reason
Flowchart	Mermaid	Better native Feishu support, high success rate
Simple Sequence Diagram	Mermaid	Concise syntax
Complex Sequence Diagram	PlantUML	Mermaid has strict complexity restrictions
Class Diagram	Mermaid	Both are available, Mermaid is more concise
ER Diagram	Mermaid	More intuitive syntax
State Diagram	Mermaid	Good support for stateDiagram-v2
Gantt Chart	Mermaid	Poor Feishu support for PlantUML Gantt charts
Pie Chart	Mermaid	Concise
Mind Map	Either	PlantUML has more flexible level markers
Use Case Diagram	PlantUML	Not supported by Mermaid
Component Diagram	PlantUML	Not supported by Mermaid
Activity Diagram with Complex Branches	PlantUML	Supports richer branch syntax

Default recommendation is Mermaid, use PlantUML only when Mermaid does not support the chart type or in complex scenarios.

5. Callout Highlight Blocks

6 Types and Background Color Mapping

Type	bgColor	Color	Markdown Syntax	Applicable Scenario
NOTE / INFO	6	Blue	`> [!NOTE]`	Supplementary explanations, prompt information
WARNING	2	Red	`> [!WARNING]`	Warnings, danger reminders
TIP	4	Yellow	`> [!TIP]`	Tips, suggestions
CAUTION	3	Orange	`> [!CAUTION]`	Notes
IMPORTANT	7	Purple	`> [!IMPORTANT]`	Important information
SUCCESS	5	Green	`> [!SUCCESS]`	Success, pass status

Usage Example

markdown

> [!NOTE]
> This is supplementary explanatory information.

> [!WARNING]
> This operation is irreversible, please proceed with caution.

> [!TIP]
> Use the `--verbose` parameter to view detailed progress.

> [!CAUTION]
> Note: The API has frequency limits.

> [!IMPORTANT]
> Environment variables must be configured before execution.

> [!SUCCESS]
> All test cases have passed.

Notes

Callout blocks cannot set
```
EmojiId
```
at the same time; types are distinguished only by
```
BackgroundColor
```
Callouts can contain child blocks (paragraphs, lists, etc.)
```
INFO
```
and
```
NOTE
```
are equivalent, both mapped to blue (bgColor=6)

6. Table Specification

9-Row Limit and Automatic Splitting

Feishu API limits a single table to a maximum of 9 rows (including header). When exceeded, feishu-cli automatically splits it into multiple tables, with each sub-table copying the header.

Splitting logic (

converter/markdown_to_block.go

Number of Table Rows	Processing Method
≤ 9 rows (including header)	Directly create a single table
> 9 rows	Split into multiple tables, each with up to 8 data rows + 1 header row

Automatic Column Width Calculation

Column width is automatically calculated based on cell content (

converter/markdown_to_block.go:25-103

Parameter	Value	Description
Chinese character width	14px	Non-ASCII characters
English character width	8px	ASCII characters
Column padding	16px	Extra padding per column
Minimum column width	80px	Cannot be narrower
Maximum column width	400px	Cannot be wider
Default document width	700px	Expand proportionally when total width is insufficient

Multi-Block Support in Cells

Table cells can contain multiple block types:

Text (plain text)
Bullet (unordered list)
Heading (heading)

Note: Feishu API automatically creates an empty Text block in each cell when creating a table. When filling content, you should update existing blocks instead of creating new ones.

Table Writing Recommendations

markdown

| Column 1 | Column 2 | Column 3 |
|-----|-----|-----|
| Data | Data | Data |

Ensure consistent number of columns per row
Large tables (more than 8 data rows) will be automatically split, no manual processing required
Column width is automatically determined by content, no manual control needed

7. Image Processing

Current Restrictions

Feishu DocX Open API does not support inserting actual image content via API. The processing method of

feishu-cli

When encountering
```
![alt](url)
```
, create an empty Image placeholder block (BlockType=27)
After import completion, the number of skipped images is displayed in the report
Users need to manually replace images in Feishu documents

Recommendations

If there are a large number of images in the document, consider manual upload after import
You can use
```
feishu-cli media upload
```
to upload materials to Feishu and obtain file tokens
The alt text related to images will be retained as placeholder information

8. Formulas

Inline Formulas

Wrap with single dollar signs:

$E = mc^2$

Supports multiple inline formulas in one paragraph:

markdown

Given $a^2 + b^2 = c^2$, when $a = 3, b = 4$, $c = 5$.

Block-Level Formulas

Wrap with double dollar signs:

markdown

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Notes

Feishu API does not support direct creation of block-level Equation (BlockType=16); it is actually downgraded to inline Equation during import
LaTeX syntax is compatible with Feishu KaTeX renderer
Special characters in formulas do not need additional escaping

9. API Restrictions and Fault Tolerance

Three-Stage Concurrent Pipeline

feishu-cli doc import

adopts a three-stage pipeline architecture (

cmd/import_markdown.go

Stage	Method	Processing Content
Stage 1	Sequential	Create all blocks in document order, create empty board placeholder blocks for charts, collect table tasks
Stage 2	Concurrent	Chart worker pool (default 5 concurrency) + table worker pool (default 3 concurrency) process simultaneously
Stage 3	Reverse Order	Process failed charts: delete empty board blocks, insert code blocks at original positions (reverse order avoids index offset)

Batch Operation Restrictions

Restriction	Value	Processing Method
Maximum number of blocks created per request	50	Automatic batching ( `batchSize = 50` )
Maximum rows per table	9	Automatic splitting with header copying
File size	Maximum 100MB	Direct error reporting when exceeded
API frequency	429 Too Many Requests	Automatic retry + linear backoff

Chart Retry and Downgrade Strategy

Error Type	Judgment Condition	Processing Method
Syntax Error	`Parse error` , `Invalid request parameter`	No retry, directly downgrade to code block
Server Error	500/502/503, `internal error`	Retry (up to 10 times, 1s interval)
Rate Limit	429, `rate limit` , `frequency limit`	Retry (classified as retryable error)
Retry Exhausted	Exceed maximum retry times	Downgrade to code block

Downgrade Processing Flow:

Get all top-level child blocks of the document
Process failed charts in reverse order by index (avoid index offset caused by deletion)
Delete empty board blocks
Insert code blocks at original positions (retain original chart code)

CLI Concurrency Control Parameters

Parameter	Default Value	Description
`--diagram-workers`	5	Number of concurrent imports for charts (Mermaid/PlantUML)
`--table-workers`	3	Number of concurrent table fill operations
`--diagram-retries`	10	Maximum number of retries for charts
`--verbose`	false	Display detailed progress

Board API Technical Details

API Endpoint:

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

```
syntax_type
```
: 1 = PlantUML, 2 = Mermaid
```
diagram_type
```
Mapping: 0=auto, 1=mindmap, 2=sequence, 3=activity, 4=class, 5=er, 6=flowchart, 7=state, 8=component

10. Best Practices Checklist

Before creating a Markdown document to be imported into Feishu, complete the following checks:

Document Structure

Heading levels do not exceed 6 (H7-H9 will be downgraded to bold paragraphs)
Nested lists use 2 or 4 spaces for indentation
Table data rows are controlled within 8 rows (avoid unnecessary splitting)
Total file size does not exceed 100MB

Mermaid Charts

Chart type is among the 8 supported types
No curly braces
```
{}
```
in labels
```
par...and...end
```
is not used
Double quotes are added to square bracket labels containing colons
SequenceDiagram: participants ≤ 8, alt layers ≤ 1
Complex charts have been split into multiple small diagrams

PlantUML Charts

Correct wrapping tags are used (
```
@startuml
```
/
```
@enduml
```
)
No leading indentation
No style directives such as
```
skinparam
```
Class diagrams do not use visibility markers (
```
+ - # ~
```
)

Special Content

Images are labeled (need manual replacement after import)
Formula syntax is correct (
```
$...$
```
for inline /
```
$$...$$
```
for block-level)
Callout types are among the 6 types (NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS)

Performance Considerations

Consider increasing
```
--diagram-workers
```
when there are a large number of charts
Consider increasing
```
--table-workers
```
when there are a large number of tables
It is recommended to add
```
--verbose
```
for the first import to observe progress

feishu-cli-doc-guide

NPX Install

Tags

SKILL.md Content (Chinese)

Feishu Document Creation Specification Guide

1. Overview

2. Full Markdown Syntax Reference

Supported Syntax and Block Type Mapping

Inline Styles

Nested List Example

3. Feishu Mermaid Syntax Specification

8 Supported Chart Types

6 Mandatory Rules

Rule 1: Forbid using curly braces {} in labels

Rule 2: Forbid using par...and...end parallel syntax

Rule 3: Avoid colons in square brackets

Rule 4: Note scope restriction

Rule 5: SequenceDiagram Complexity Threshold

Rule 6: Avoid overly complex nested structures

Pre-Generation Checklist

4. PlantUML Safe Subset

Global Rules

Notes by Chart Type

Mermaid vs PlantUML Selection Strategy

5. Callout Highlight Blocks

6 Types and Background Color Mapping

Usage Example

Notes

6. Table Specification

9-Row Limit and Automatic Splitting

Automatic Column Width Calculation

Multi-Block Support in Cells

Table Writing Recommendations

7. Image Processing

Current Restrictions

Recommendations

8. Formulas

Inline Formulas

Block-Level Formulas

Notes

9. API Restrictions and Fault Tolerance

Three-Stage Concurrent Pipeline

Batch Operation Restrictions

Chart Retry and Downgrade Strategy

CLI Concurrency Control Parameters

Board API Technical Details

10. Best Practices Checklist

Document Structure

Mermaid Charts

PlantUML Charts

Special Content

Performance Considerations

Rule 1: Forbid using curly braces
`{}`
in labels

Rule 2: Forbid using
`par...and...end`
parallel syntax