feishu-cli-doc-guide

Feishu Markdown Compatibility Guide

Before generating Markdown to be imported into Feishu, check according to this guide. For import execution use feishu-cli-import, for editing existing documents use feishu-cli-write。

Quick Check

Content	Required Check Items
Mermaid	No curly brace tags, no par...and...end、sequenceDiagram participant ≤ 8
PlantUML	No leading-line indentation, no skinparam/!define, for class diagrams do not write + - # ~ visibility
Tables	Rows > 9 can be imported into the same block; columns > 9 will be split into column groups; for very large tables, Sheet is recommended
Images	doc import uploaded by default;doc add/content-update requires passing --upload-images
Formulas	Inline $...$; block-level formulas are imported as Text+Equation elements
Callout	Only NOTE/WARNING/TIP/CAUTION/IMPORTANT/SUCCESS

Mermaid

Mermaid is recommended; the Feishu server supports 8 common diagram types.

Type	Declaration	Import Strategy
Flowchart	flowchart TD / flowchart LR	doc import automatic;board import --diagram-type flowchart
Sequence Diagram	sequenceDiagram	doc import automatic; for complex diagrams, splitting is recommended
Class Diagram	classDiagram	board import --diagram-type class
State Diagram	stateDiagram-v2	doc import auto；board import --diagram-type state
ER Diagram	erDiagram	board import --diagram-type er
Gantt Chart	gantt	auto
Pie Chart	pie	auto
Mind Map	mindmap	board import --diagram-type mindmap

Mandatory rules:

1. Do not write Flowchart labels {}。A{判断} can express a diamond, but the label text must not contain curly braces.
2. sequenceDiagram does not use par...and...end, change to Note over A,B: 并行执行。
3. sequenceDiagram participants are recommended to be ≤ 8,alt/opt/loop do not nest too deeply.
4. Replace long labels with short sentences, avoiding 30+ long messages stacked with complex structures.
5. State diagrams must use stateDiagram-v2。

For more details see references/mermaid-spec.md。

PlantUML

Use PlantUML only for diagram types that Mermaid does not cover.

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

Rules:

• Must have @startuml / @enduml。
• Do not use leading-line indentation.
• Avoid skinparam, macros, colors, fonts, direction control.
• For class diagram members write field : type、method(), do not write +field、-method()。

Tables

Ordinary Markdown tables can be imported into docx:

• Row count > 9: for CLI use insert_table_row append to the same table block.
• Column count > 9: split by column groups, keeping the first column to identify rows.
• For data tables, long tables, and content that needs sorting and filtering, generate a Sheet first:feishu-cli sheet import-md。

Callout

> [!NOTE]
> 普通提示

> [!WARNING]
> 风险提示

Supports:NOTE、WARNING、TIP、CAUTION、IMPORTANT、SUCCESS. A Callout can contain paragraphs and lists.

Images and Files

![说明](./image.png)
![远程图](https://example.com/image.png)

doc import uploads local and network images by default.doc add/content-update must explicitly pass --upload-images. For precise insertion of video/file types use feishu-cli doc media-insert。

Extension Tags

These tags appear when exporting and re-importing; the import side supports roundtrip:

<mention-user id="ou_xxx"/>
<mention-doc token="doc_token_xxx" type="docx">标题</mention-doc>
<callout type="NOTE">内容</callout>
<grid cols="2"><column>左</column><column>右</column></grid>
<sheet rows="5" cols="5"/>

When writing by hand, use only the tags you actually need; for ordinary content, prefer standard Markdown.

Pre-import Validation

1. The file must be UTF-8 and must not contain the U+FFFD replacement character.
2. Scan Mermaid/PlantUML once according to the rules above.
3. The image path must be resolvable from the directory where the Markdown file is located.
4. Move oversized tables to a Sheet to avoid excessively long document import times.