md-to-feishu

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown to Feishu Document

将Markdown转换为飞书文档

Convert a local Markdown file into a Feishu document, with automatic image upload.

将本地Markdown文件转换为飞书文档，支持自动图片上传。

User Input

用户输入

The user only needs to provide a Markdown file path. Title is optional — if not provided, extract it automatically (see below).

用户仅需提供Markdown文件路径。标题为可选项——若未提供，将自动提取（详见下文）。

Step 1: Determine the Document Title

步骤1：确定文档标题

Read the Markdown file and look for the first
```
# heading
```
— use that as the title.
If no
```
# heading
```
exists, scan the content and generate a concise, descriptive title based on the topic.
If the user explicitly provides a title, use that instead.

读取Markdown文件，查找第一个
```
# 标题
```
——将其作为文档标题。
若不存在
```
# 标题
```
，则扫描内容并根据主题生成简洁、描述性的标题。
若用户明确提供标题，则优先使用该标题。

Step 2: Check the Runtime Environment

步骤2：检查运行环境

Try each option in order. Use the first one that works.

按顺序尝试以下选项，使用第一个可用的选项。

Option A: uvx (preferred)

选项A：uvx（推荐）

bash

which uvx

uvx

is available, the run command is:

bash

uvx feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>

uvx

runs with Python < 3.11, add

--python 3.11

bash

uvx --python 3.11 feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>

bash

which uvx

若

uvx

可用，运行命令如下：

bash

uvx feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>

若

uvx

运行时使用的Python版本低于3.11，需添加

--python 3.11

：

bash

uvx --python 3.11 feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>

Option B: feishu-docx already installed

选项B：已安装feishu-docx

bash

which feishu-docx

If found, check Python version:

bash

python3 --version

If Python >= 3.11, the run command is:

bash

feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>

bash

which feishu-docx

若找到该工具，检查Python版本：

bash

python3 --version

若Python版本≥3.11，运行命令如下：

bash

feishu-docx create "<TITLE>" -f <MARKDOWN_FILE_PATH>

Option C: Nothing available — install guidance

选项C：无可用环境——安装指引

If neither

uvx

nor

feishu-docx

is found, tell the user:

feishu-docx

requires Python >= 3.11. Install with one of:

bash

# Recommended: install uv, then run directly without global install
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx feishu-docx create "Title" -f file.md

# Or: install globally with pip (Python >= 3.11 required)
pip install feishu-docx

Feishu credentials must be configured first:

bash

feishu-docx config set --app-id <APP_ID> --app-secret <APP_SECRET>

Then stop and wait for the user to set up the environment.

若未找到

uvx

或

feishu-docx

，告知用户：

feishu-docx

要求Python版本≥3.11。可通过以下方式安装：

bash

# 推荐：安装uv后直接运行，无需全局安装
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx feishu-docx create "Title" -f file.md

# 或者：使用pip全局安装（需Python≥3.11）
pip install feishu-docx

需先配置飞书凭证：

bash

feishu-docx config set --app-id <APP_ID> --app-secret <APP_SECRET>

然后停止操作，等待用户完成环境配置。

Step 3: Pre-process Mermaid Blocks

步骤3：预处理Mermaid代码块

The

feishu-docx

tool cannot handle Mermaid code blocks. Before uploading, check if the Markdown contains any

```mermaid

blocks and convert them to images first.

feishu-docx

工具无法处理Mermaid代码块。上传前，需检查Markdown中是否包含

```mermaid

代码块，并先将其转换为图片。

3a: Scan for Mermaid blocks

3a：扫描Mermaid代码块

Read the Markdown file and check if it contains any

```mermaid

fenced code blocks. If none are found, skip to Step 4.

读取Markdown文件，检查是否包含

```mermaid

围栏代码块。若未找到，直接跳至步骤4。

3b: Create a temporary copy

3b：创建临时副本

Copy the original Markdown file to a temp file in the same directory (so relative image paths still work):

<original-name>.feishu-tmp.md

For example:

blog_post.md

→

blog_post.feishu-tmp.md

All subsequent modifications happen on this temp copy. The original file is never modified.

将原始Markdown文件复制到同一目录下的临时文件中（确保相对图片路径仍有效）：

<原文件名>.feishu-tmp.md

例如：

blog_post.md

→

blog_post.feishu-tmp.md

后续所有修改均在该临时文件上进行，原始文件不会被修改。

3c: Render Mermaid diagrams to PNG

3c：将Mermaid图表渲染为PNG图片

For each

```mermaid ... ```

block in the temp file, render it to a PNG image using the mermaid.ink API:

python

import base64, urllib.request

def render_mermaid(code: str, output_path: str):
    """Render a Mermaid diagram to PNG via mermaid.ink API."""
    encoded = base64.urlsafe_b64encode(code.encode()).decode()
    url = f"https://mermaid.ink/img/{encoded}?bgColor=white"
    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
    resp = urllib.request.urlopen(req, timeout=30)
    with open(output_path, "wb") as f:
        f.write(resp.read())

Important: The

User-Agent

header is required — mermaid.ink returns 403 without it.

Save rendered images to the same directory as the Markdown file, using descriptive filenames based on diagram content:

GOOD:

mermaid-architecture-overview.png

mermaid-data-flow.png

BAD:
```
mermaid-1.png
```
,
```
diagram.png
```

对于临时文件中的每个

```mermaid ... ```

代码块，使用mermaid.ink API将其渲染为PNG图片：

python

import base64, urllib.request

def render_mermaid(code: str, output_path: str):
    """通过mermaid.ink API将Mermaid图表渲染为PNG图片。"""
    encoded = base64.urlsafe_b64encode(code.encode()).decode()
    url = f"https://mermaid.ink/img/{encoded}?bgColor=white"
    req = urllib.request.Request(url, headers={"User-Agent": "Mozilla/5.0"})
    resp = urllib.request.urlopen(req, timeout=30)
    with open(output_path, "wb") as f:
        f.write(resp.read())

重要提示： 必须添加

User-Agent

请求头——若无此头，mermaid.ink将返回403错误。

将渲染后的图片保存至Markdown文件所在目录，使用基于图表内容的描述性文件名：

3d: Replace Mermaid blocks with image references

3d：替换Mermaid代码块为图片引用

In the temp copy, replace each

```mermaid ... ```

block with a Markdown image reference:

markdown

![Architecture overview](mermaid-architecture-overview.png)

Use relative paths from the temp file to the rendered images.

在临时文件中，将每个

```mermaid ... ```

代码块替换为Markdown图片引用：

markdown

![架构概览](mermaid-architecture-overview.png)

使用从临时文件到渲染后图片的相对路径。

3e: Use the temp file for upload

3e：使用临时文件进行上传

From this point, the temp file becomes the

<MARKDOWN_FILE_PATH>

used in Step 4.

从此时起，临时文件将作为步骤4中使用的

<MARKDOWN_FILE_PATH>

。

Step 4: Run the Command

步骤4：运行命令

Run from the directory where the Markdown file lives (or where its relative image paths resolve correctly), so that local image references work.
The tool will:
- Convert Markdown blocks to Feishu format
- Automatically upload local images referenced in the Markdown
- Wait ~10s for block consistency before uploading images

在Markdown文件所在目录运行命令（或其相对图片路径可正确解析的目录），确保本地图片引用有效。
该工具将：
- 将Markdown块转换为飞书格式
- 自动上传Markdown中引用的本地图片
- 等待约10秒以确保块一致性，再上传图片

Step 5: Clean Up

步骤5：清理文件

If a temp file was created in Step 3:

Delete the temp Markdown file (
```
*.feishu-tmp.md
```
)
Delete all rendered Mermaid PNG files created in Step 3c (they were only needed for the upload)

若步骤3中创建了临时文件：

删除临时Markdown文件（
```
*.feishu-tmp.md
```
）
删除步骤3c中创建的所有Mermaid渲染PNG图片（仅上传时需要）

Step 6: Report Result

步骤6：反馈结果

Show the user:

Number of blocks converted and images uploaded
The created document ID
Success or failure status

If it fails with authentication errors, remind the user to configure credentials:

bash

feishu-docx config set --app-id <APP_ID> --app-secret <APP_SECRET>

向用户展示：

转换的块数量和上传的图片数量
创建的文档ID
操作成功或失败状态

若因认证错误导致失败，提醒用户配置凭证：

bash

feishu-docx config set --app-id <APP_ID> --app-secret <APP_SECRET>