Notion で「Markdown & CSV でエクスポート」を押したら、ファイル名の末尾に 32 文字のページ ID が付き、Callout ブロックは生の HTML として書き出され、トグルは折りたたみが外れた並列段落になった ZIP が届きました。あるいはページを直接エディタに貼り付けたところ、style 付きの span だらけになりました。Notion からきれいな Markdown を取り出す作業は、実は 1 つのフローではなく 2 つあり、状況に合った方を選ぶだけで手直しの時間が大きく変わります。
どちらのルートを使うか
どちらのルートも、最終的に到達する場所は同じ — Obsidian や静的サイトジェネレータ、README、LLM のプロンプトにそのまま入れられる Markdown です。違いは出発点と、後で何を直すか、の 2 点です。
- ルート A — Markdown & CSV の ZIP エクスポート。ワークスペース全体、あるいはページツリーごとまとめて移行したい。UUID 混じりのファイル名、Callout の HTML、同期ブロックの重複を、一括で直しても構わない。この場合は下の ルート A を読んでください。
- ルート B — HTML でエクスポートしてブラウザ内で変換。対象は 1 ページか数ページで、社外秘の内容が含まれるためどこにもアップロードしたくない。最初からきれいな出力が欲しい。この場合は下の ルート B を読んでください。
自動パイプラインを組みたい場合は、2026 年 3 月に登場した Notion 公式の Markdown Content API という第 3 の選択肢があります。こちらは両ルートの後で紹介します。
Notion はどうやって Markdown を生成しているのか
Notion はブロック型のエディタです。ページは「段落 / 見出し / リスト項目 / データベース / Callout / トグル / 同期ブロック / 数式 / 埋め込み」といったブロックのツリーで、このうち Markdown に対応する記法があるのはごく一部です。「Markdown でエクスポート」を選ぶと Notion はこのツリーを走査して、その場で書ける最も近い形を出力します。Markdown に対応物がないブロックは、落ちるか、平坦化されるか、生の HTML のまま残ります。
Notion 公式ヘルプは、Callout ブロックについて「Markdown に該当構文がないため HTML として書き出される」と明示しています別タブで開きます。同ページには Windows のフォルダ構造が既定の MAX_PATH 260 文字上限に引っかかる警告と、7-Zip 使用の推奨も載っています。それ以外の癖については書かれておらず、ZIP を開いてはじめて気づくことになります。
ネイティブの Markdown & CSV エクスポート手順
どちらのルートを選ぶ場合でも、エクスポートの操作自体は共通です。ページ右上の「•••」→「エクスポート」を開き、形式を「Markdown & CSV」に設定します。Business / Enterprise プランでは「サブページを含める」を有効化するとページ配下のツリーごと 1 つの ZIP に含められます。ワークスペース全体のエクスポートは「Settings → Workspace → General」から実行でき、大規模ワークスペースでは処理に数時間かかることもあります。
ルート A — Markdown & CSV の ZIP エクスポートを整形する
ZIP を展開すると、次の 8 つの癖が毎回同じ形で出てきます。ここではそれぞれの直し方を紹介します。
ファイル名とページリンクに 32 文字のページ ID が付く
エクスポートされる .md ファイル名の末尾には、多くの場合「タイトル + 半角スペース + 32 文字の 16 進ページ ID」が付き、[ページ mention] リンクも同じ ID 付きファイル名を指しています。手作業でファイル名を書き換えるとリンクが全滅します。定番の直し方は 2 パス処理です — まず全ファイル名から「ID → タイトル」の対応表を作り、続いて全 Markdown 内のリンクを書き換え、最後にファイルをきれいなタイトルへリネームします。同じパターンは Notion's Markdown Export Quirks別タブで開きます でも解説されています。
Windows の 260 文字パス上限
Notion のネストしたページ構造は、My Team's Handbook a1b2c3.../Onboarding e4f5g6.../Week 1 tasks h7i8j9....md のような長いパスを生成します。Windows では既定の MAX_PATH 260 文字を簡単に超えるため、Notion 公式ヘルプは「フォルダ作成オプションを切る」か「7-Zip で展開する」を勧めています。macOS と多くの Linux ファイルシステムには、同じ 260 文字の上限はありません。
Callout ブロックが生の HTML になる
絵文字と背景色付きの Notion Callout は、Markdown のブロッククォートではなく、インラインの HTML として出力されます。Notion 公式ヘルプがこの挙動を確認しています。多くの Markdown レンダラは inline HTML をそのまま素通しするため、Notion で見えていた背景色付きの表示にはならず、ブラウザの既定スタイルに従った平坦な表示になります。実務的な直し方は 2 択です — Callout を > ブロッククォートに書き換える（絵文字と色は失われます）か、掲載先のレンダラが GFM の Admonition (> [!NOTE]) をサポートしているならそのパターンへ変換する、のどちらかです。
トグルが折りたたみを失う場合がある
Notion のトグルは「見出しの下に折りたたまれたコンテンツ」を配置する構造ですが、Markdown & CSV エクスポートでは折りたたみのラッパーが失われることがあり、見出しと本文が並列の段落として並びます。GitHub や静的サイトで折りたたみを残したい場合は、手で <details><summary>...</summary>...</details> で包み直します。両方とも Markdown が許容するインライン HTML です。
同期ブロックが複数ファイルに複製される
同期ブロックは Notion 内では 1 つの実体を複数ページで共有する仕組みですが、エクスポート時は各ページ側で個別に解決されます。同じ内容がすべての参照元ファイルに書き込まれる、つまり複製されます。この状態のまま RAG や検索インデックスに投入すると、ほぼ同一のチャンクが並んでノイズになります。対策は手動です。同期ブロックごとに正典 (canonical) となるページを 1 つ決め、他ファイルの重複を取り除きます。
数式と埋め込みは素のテキストになる
Notion の LaTeX 数式は $...$ あるいは $$...$$ の生テキストで出力されます。Obsidian は数式としてレンダーし、GitHub も 2022 年以降 $…$ と $$…$$ を数式としてネイティブにサポートしています別タブで開きます。それ以外のレンダラでは素のテキストのままです。動画・Figma・Twitter の埋め込みは、通常は素の URL 1 行だけになります。Markdown 画像でもなく iframe でもありません。
画像パスがエクスポートのフォルダ構造に依存する
画像は各ページ隣の添付フォルダに置かれ、Markdown 内のリンクはそのフォルダを指す相対パスです。.md ファイル 1 つだけを新しい場所に移すと、隣にあった添付フォルダが付いてこないため、全ての画像リンクが切れます。解決策は 2 つ。ファイルを添付フォルダごと移動するか、画像パスを /assets/ のような中央置き場に統一してファイルもそちらへ移動するか、のいずれかです。
データベースは CSV になり Markdown 表にはならない
フルページのデータベースは CSV として書き出され、各行のページは同名フォルダの中に個別 .md として並びます。Markdown テーブルとしての表現はどこにも生成されず、ビュー（フィルタ / ソート / グループ化）、リレーション、ロールアップ、フォーミュラも保持されません。データベースを Markdown 表として使いたい場合は、CSV を CSV to Markdown に流すとパイプ表がそのまま出ます。データベース多用のワークスペースなら、この一手だけで移行時間が大きく変わります。
ルート B — HTML でエクスポートしてブラウザ内で変換する
数ページだけで、内容がプロダクト計画・契約書・社内ナレッジのようにアップロード禁止のものだと、実務的な最短路は HTML です。
Notion のエクスポート形式は Markdown & CSV / HTML / PDF の 3 種類あり、この中で HTML は最もリッチです。Callout はインライン HTML として構造を保ち、トグルのラッパーも維持され、ページ間リンクも残ります。
流れは次の通りです。
- Notion で対象ページを開き、右上の「•••」→「エクスポート」→「HTML」を選択（必要ならサブページを含める）。
- 出力された
.htmlを開くか、内容をコピーします。 - HTML to Markdown に貼り付けて実行ボタンを押します。
- 出てきた Markdown を Obsidian、CMS、あるいは LLM プロンプトへ貼り付けます。
変換はブラウザ内だけで走り、リクエストはページから出ません。アカウント登録も OAuth 認可もワークスペーストークンの発行も不要です。この差は、オンライン変換は安全か で扱っている「アップロード型はその瞬間にファイルの支配権が手元から離れる」というリスクを避けたい場面で効きます。
変換で残るもの: 見出し・リスト・リンク・表・コードブロック・太字・斜体。落ちるもの: inline style 属性、class 名、ラッパーの <div>、data-* 属性、その他 Markdown に対応構文がない装飾マークアップ。Notion の Callout タグ自体は inline HTML としてそのまま残りますが、Notion アプリ内での装飾（背景色や絵文字の視認性）は付いてきません。目的が LLM への投入なら、LLM のための Markdown と HTML 比較 で「Markdown のほうがトークン予算を消費しない」理由を確認しておくと選択しやすくなります。HTML 貼り付けの一般的な整形パターンは HTML 貼り付け Markdown 化 で扱っています。
ルート C — Notion Markdown Content API（API バージョン 2026-03-11）
Notion は 2026 年にファーストパーティの Markdown コンテンツエンドポイントを追加しました。公式デベロッパードキュメント別タブで開きます がこの API 面を解説しており、リクエストには API バージョンヘッダ 2026-03-11 を指定する必要があります。ブロックツリーを 1 ブロックずつ翻訳する代わりに、次の 1 リクエストで済みます。
GET /v1/pages/{id}/markdown— ページを Markdown で取得POST /v1/pages（markdownを body に含める）— Markdown からページを作成PATCH /v1/pages/{id}/markdown— Markdown でページ本文を更新
Notion はこの形式を Enhanced Markdown と呼んでいます。見出し・リスト・リンク・強調は普通の Markdown ですが、CommonMark に対応物がないブロックは XML 風のタグ — Callout は <callout>...</callout>、トグルは <details><summary>...</summary>...</details>、<database> はデータベース本体でなく参照タグ、として表現されます。受け側のツールがこれらのタグを理解できるなら、ルート A で失われる情報を保ったまま渡せます。理解できないなら、その場でスクリプトから剥がすか書き換えます。これらのエンドポイントは、public integration だけでなく internal と personal のトークンにも対応します。
覚えておくと役立つ注意点が 2 つあります。
- ファイル系ブロック（画像・PDF）は署名付き URL で返ります。この URL は期限付きなので、同じジョブ内で実体をダウンロードしてください。Markdown だけをアーカイブしても後で画像が消えます。
- 約 20,000 ブロックを超えるページはレスポンスが truncate され、
unknown_block_idsが返ります。追加取得は別リクエストで行います。
単発のページや第三者と共有できないページなら、HTML → FormatArc のルート B が早いです。API が真価を発揮するのは、リポジトリの中で Notion → CMS や Notion → RAG の自動パイプラインを組み、ローテーション可能なトークンで運用できる場面です。
比較 — Notion から Markdown を取り出す 4 通り
| 手段 | 向いている用途 | Callout / トグル | UUID を含むか | ブラウザ内で完結 |
|---|---|---|---|---|
| ネイティブ Markdown & CSV エクスポート | ワークスペース全体を一括移行、まとめて手直し | Callout は生 HTML、トグルはラッパーが外れる場合あり | 含む（ファイル名・リンク先） | Yes（ZIP はローカル） |
| Notion HTML エクスポート → HTML to Markdown | 社外秘の 1〜数ページ | Callout はインライン HTML で維持、トグルは <details> 維持 | 含まない | Yes |
| notion-to-md別タブで開きます npm ライブラリ | ブロック単位で挙動を調整するカスタムパイプライン | ブロック単位で設定可能 | 設定可能 | Yes（Node / CLI） |
Notion Markdown Content API（API バージョン 2026-03-11） | API トークン付きの自動パイプライン | <callout> / <details> の Enhanced Markdown タグ | 含まない（ファイル出力なし） | No（サーバ側呼び出し） |
よくある質問
なぜ Notion はエクスポートファイル名に 32 文字のページ ID を入れるのですか
Notion 内部では、すべてのブロックとページに ID が振られています。エクスポート時、同じタイトルのページ（例: 「議事録」が複数）が同じフォルダ内で衝突しないよう、ファイル名の末尾にページ ID を付けるのが一般的です。代償は「読めないファイル名」と「Windows のパス長違反」です。HTML エクスポートと Markdown Content API は、それぞれ「単一 HTML ファイルで完結」「API レスポンスで完結」なのでこの問題を持ち込みません。
オンラインの Notion → Markdown 変換ツールに社外秘ページを渡しても安全ですか
そのツールがブラウザ内型か、サーバ側型かで結論が変わります。ブラウザ内型（FormatArc の HTML to Markdown など）は貼り付けた内容を手元の JavaScript で処理するため、何もアップロードされません。サーバ側 SaaS はファイルを受信します。プロダクト計画・契約書・未発表ドキュメントなどでは、オンライン変換は安全か の判定基準（ネットワークタブでリクエスト有無を確認する等）が事故防止に効きます。
API とエクスポート、どちらを使うべきですか
API は自動化の反復ジョブに向いています — Notion のページを静的サイトのビルドに流し込む、RAG インデックスと同期を保つ、数百ページ規模の移行を定期実行する、といった場面です。単発の一括移行で、後で手作業のクリーンアップを許容できるならエクスポート（Markdown & CSV）で十分です。社外秘の単発ページで、サーバに触れずにきれいな出力が欲しい、ならエクスポート（HTML）+ FormatArc が最短です。
Notion Markdown Content API は Callout やトグルを保持しますか
はい。Enhanced Markdown タグで表現されます — Callout は <callout>...</callout>、トグルは <details><summary>...</summary>...</details> です。どちらも CommonMark が許容するインライン HTML で、GitHub は <details> を実動の折りたたみとしてレンダーします。Callout がそのままレンダーされるのは Notion 内だけなので、他プラットフォームに載せるときはスタイルを自前で当てるか、ブロッククォートへ書き換えます。
エクスポート時、データベースはどうなりますか
ネイティブの Markdown & CSV エクスポートでは、各データベースは ZIP のトップに CSV として書き出され、行のページはそれぞれ同名フォルダの中に .md として並びます。ビュー（フィルタ / ソート / グループ化）は保持されません。データベースを Markdown 表として使いたい場合は CSV to Markdown に CSV を流します。行ごとの詳細ページも欲しいなら両方を組み合わせます。
まとめ
Notion の Markdown エクスポートは壊れているというより、lossy です。ルート A はワークスペース全体を一度に手に入れる代わりに、8 種類の癖を一括で直す作業が付いてきます。ルート B は HTML to Markdown を使い、社外秘のページもブラウザ内だけで Markdown に変換できます。アカウント登録も OAuth 認可も不要です。Markdown Content API（API バージョン 2026-03-11）は、自動パイプライン向けの第 3 の選択肢としてこの間に収まります。HTML → Markdown の一般的な変換パターンは HTML を Markdown に変換するガイド で、Markdown を LLM に渡す観点は LLM のための Markdown と HTML 比較 で確認できます。