md-to-feishu

Markdown から Feishu ドキュメントへの変換

ローカルの Markdown ファイルを Feishu ドキュメントに変換し、画像を自動的にアップロードします。

ユーザー入力

ユーザーが指定する必要があるのは、Markdown ファイルのパスだけです。タイトルは省略可能です。指定されていない場合は、自動的に抽出します（下記を参照）。

ステップ 1：ドキュメントのタイトルを決定する

1. Markdown ファイルを読み込み、最初の # heading を探します。見つかった場合は、それをタイトルとして使用します。
2. # heading がない場合は、内容を確認し、トピックに基づいて簡潔で説明的なタイトルを生成します。
3. ユーザーがタイトルを明示的に指定した場合は、そのタイトルを使用します。

ステップ 2：実行環境を確認する

各オプションを順番に試し、最初に動作したものを使用します。

オプション A：uvx（推奨）

which uvx

uvx が利用可能な場合、実行コマンドは次のとおりです。

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

uvx の実行に使われる Python が 3.11 未満の場合は、--python 3.11 を追加します。

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

オプション B：feishu-docx がすでにインストールされている場合

which feishu-docx

見つかった場合は、Python のバージョンを確認します。

python3 --version

Python が 3.11 以上の場合、実行コマンドは次のとおりです。

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

オプション C：何も利用できない場合 — インストール方法の案内

uvx も feishu-docx も見つからない場合は、ユーザーに次のように伝えます。

feishu-docx には Python 3.11 以上が必要です。次のいずれかの方法でインストールしてください。

# 推奨：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

Feishu の認証情報を先に設定する必要があります。

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

その後は処理を停止し、ユーザーが環境を設定するのを待ちます。

ステップ 3：Mermaid ブロックを前処理する

feishu-docx ツールは Mermaid のコードブロックを処理できません。アップロード前に、Markdown に ```mermaid ブロックが含まれていないか確認し、含まれている場合は先に画像に変換します。

3a：Mermaid ブロックを検索する

Markdown ファイルを読み込み、```mermaid で始まるフェンス付きコードブロックが含まれているか確認します。見つからない場合は、ステップ 4 に進みます。

3b：一時コピーを作成する

相対画像パスがそのまま使えるように、元の Markdown ファイルを同じディレクトリ内の一時ファイルにコピーします。

<original-name>.feishu-tmp.md

例：blog_post.md → blog_post.feishu-tmp.md

以降の変更はすべて、この一時コピーに対して行います。元のファイルは変更しません。

3c：Mermaid 図を PNG にレンダリングする

一時ファイル内の各 ```mermaid ... ``` ブロックを、mermaid.ink API を使って PNG 画像にレンダリングします。

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())

重要： User-Agent ヘッダーは必須です。指定しない場合、mermaid.ink は 403 を返します。

レンダリングした画像は Markdown ファイルと同じディレクトリに保存し、図の内容に基づく説明的なファイル名を付けます。

• 良い例：mermaid-architecture-overview.png、mermaid-data-flow.png
• 悪い例：mermaid-1.png、diagram.png

3d：Mermaid ブロックを画像参照に置き換える

一時コピー内で、各 ```mermaid ... ``` ブロックを Markdown の画像参照に置き換えます。

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

一時ファイルからレンダリングした画像への相対パスを使用します。

3e：アップロードに一時ファイルを使用する

この時点から、一時ファイルをステップ 4 で使用する <MARKDOWN_FILE_PATH> とします。

ステップ 4：コマンドを実行する

• ローカル画像参照が正しく解決されるように、Markdown ファイルがあるディレクトリ（または相対画像パスが正しく解決されるディレクトリ）から実行します。
• ツールは次の処理を行います。
  • Markdown ブロックを Feishu 形式に変換する
  • Markdown 内で参照されているローカル画像を自動的にアップロードする
  • 画像をアップロードする前に、ブロックの整合性が取れるまで約 10 秒待機する

ステップ 5：クリーンアップする

ステップ 3 で一時ファイルを作成した場合：

• 一時 Markdown ファイル（*.feishu-tmp.md）を削除します。
• ステップ 3c で作成した Mermaid PNG ファイルをすべて削除します（アップロードにのみ必要なファイルです）。

ステップ 6：結果を報告する

ユーザーに次の情報を示します。

• 変換されたブロック数とアップロードされた画像数
• 作成されたドキュメント ID
• 成功または失敗のステータス

認証エラーで失敗した場合は、認証情報の設定をユーザーに案内します。

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