經營開發部落格久了，總會遇到平台搬家或備份既有文章的狀況。Medium、Dev.to、Hashnode，再加上日本開發者生態系主流的 Qiita 與 Zenn，寫文章時大多支援 Markdown，但真正要離開平台時（匯出），各家提供的資料格式卻不盡相同：有的把 Markdown 原稿原封不動還給你，有的用 JSON 打包匯出，Medium 則只提供裝了 HTML 檔案的 ZIP 壓縮檔。
本文將整理各平台的文章擷取方式與資料格式差異、frontmatter 重建、Qiita 到 Zenn 的四步驟搬家流程，以及只剩 HTML 時如何還原成 Markdown。如果你手上只剩公開頁面的 HTML，可以把它貼到 HTML to Markdown 裡，在瀏覽器中直接還原成 Markdown，轉換全程不經過外部伺服器。
各平台文章擷取方式與資料格式比較
每個平台的匯出功能所提供的資料格式都不同。規劃搬家或備份時，可以參考下列格式對照表。
| 平台 | 文章擷取方式 | 提供的資料格式 |
|---|---|---|
| Dev.to | 透過 編輯器指南在新分頁中開啟 中記載的 API 取得，或善用 社群匯出工具在新分頁中開啟 | Markdown + frontmatter |
| Hashnode | 儀表板批量匯出為 JSON；單一文章可在 URL 末尾加 .md 取得 Markdown 原稿（官方變更紀錄在新分頁中開啟） | JSON / Markdown |
| Medium | 透過「Download your information在新分頁中開啟」下載包含 posts/ 資料夾的 ZIP | HTML（無 Markdown 匯出選項） |
| Qiita（日本） | 透過 API v2在新分頁中開啟 取得每篇文章的 Markdown（body）與 HTML（rendered_body） | Markdown + HTML |
| Zenn（日本） | 透過 連結的 GitHub 儲存庫在新分頁中開啟 以本地 Markdown 檔案管理 | Markdown |
搬家的起點不是「要去哪裡」，而是「手上有什麼格式的資料」。
- 手上是 Markdown 檔案：直接進入語法差異檢查與 frontmatter 重構步驟。
- 手上是 JSON 檔案：從 JSON 物件中抽出 Markdown 欄位（可善用社群工具把 Hashnode 匯出的 JSON 拆分成
.md檔案）。 - 手上是 HTML 檔案：必須先轉換成 Markdown。Medium 與過去網頁備份就屬於這種情況。
從 Dev.to、Hashnode、Medium 擷取文章
從 Dev.to 取得文章
Dev.to 的編輯器本身就是純 Markdown 基底，是搬家最輕鬆的平台之一。每篇貼文都帶有 Jekyll 風格的 frontmatter，包含 title、published、tags、canonical_url、cover_image、series 等欄位（Dev.to 編輯器指南在新分頁中開啟）。在設定頁面簽發 API 金鑰後，呼叫 API 端點即可取得包含 Markdown 原稿的文章列表；利用 Dev.to-exporter在新分頁中開啟 這類社群腳本，一條指令就能把所有文章以 .md 檔案儲存在本地。
從 Hashnode 取得文章
Hashnode 提供兩條路徑：
- 儀表板的備份匯出功能會把所有文章下載為單一 JSON 檔案。可用 hashnode-export-to-markdown在新分頁中開啟 這類工具把 JSON 拆分回帶有 frontmatter 的個別 Markdown 檔案。
- 2026 年 6 月起，在單一文章 URL 末尾加上
.md，或用Accept: text/markdown標頭請求，就能直接看到原始 Markdown（官方變更紀錄在新分頁中開啟）。要快速搬幾篇文章時很方便。
反過來說，如果想把外來的 Markdown 檔案匯入 Hashnode，可以透過儀表板的 批量 Markdown 匯入在新分頁中開啟 功能，以 ZIP 檔一次登記。
從 Medium 取得文章
Medium 匯出時不提供 Markdown。在帳號設定的「Download your information在新分頁中開啟」中下載的 ZIP 檔，posts/ 資料夾裡每篇文章對應一個 HTML 檔案。轉為 Markdown 有兩種方式：
- 用
mediumexporter或medium-2-md等 CLI 工具批量轉換 - 數量不多的話，直接把 HTML 內容複製貼到 HTML to Markdown 中
轉換在瀏覽器內完成，未公開的草稿或尚未發布的文章，也不必擔心資料外洩到外部伺服器。線上轉換工具使用前該做的隱私檢查，詳見 線上安全：轉換工具使用前必做的 5 項隱私檢查（2025 年外洩事件）。
Qiita 到 Zenn（及標準 GFM）的四步驟搬家
Qiita 與 Zenn 是日本技術部落格生態系的代表，兩者的搬家（或把 Qiita 文章移到 GitHub 基底的部落格）是一套典型的四步驟模型：
- 透過 API 擷取原始文章資料
- 把平台特有語法轉換為目標語法
- 組建 frontmatter 並保留發布日期（
published_at） - 圖片與程式碼區塊後處理
步驟一：透過 API 擷取原始文章
Qiita 提供官方 API v2在新分頁中開啟，可以批量取得包含 Markdown 原稿的文章資料。在設定中簽發個人存取權杖，放入標頭中，呼叫已認證使用者的文章列表端點。
curl -H "Authorization: Bearer YOUR_TOKEN" \
"https://qiita.com/api/v2/authenticated_user/items?page=1&per_page=100" > items.json
擷取時需要確認的三件事（以官方文件在新分頁中開啟為準）：
- 回應中的
body欄位是 Markdown 原稿，rendered_body是渲染後的 HTML。搬家時使用body。 per_page上限為 100。超過 100 篇時需遞增page編號反覆呼叫。- API 呼叫限制：認證時每小時 1,000 次，未認證時每 IP 每小時 60 次。個人部落格搬家綽綽有餘。
步驟二：平台特有語法轉換與相容性檢查
基礎的 Markdown 語法（標題、清單、連結、表格）是相容的，但各平台的容器語法或擴充語法需要改寫。主要對照如下（以 Qiita 語法速查表在新分頁中開啟 與 Zenn Markdown 指南在新分頁中開啟 為準）。
| 元素 | Qiita 語法 | Zenn 語法 |
|---|---|---|
| 提示框 | :::note info | :::message |
| 警示框 | :::note warn / :::note alert | :::message alert |
| 摺疊/展開 | <details><summary> 標籤 | :::details 標題 |
| 程式碼區塊檔名 | ```ruby:qiita.rb | 支援相同語法 |
| 公式區塊 | ```math | $$（前後需空行） |
| 行內公式 | $`公式`$ | $公式$ |
要注意的是，Qiita 的提示框有 info、warn、alert 三種，Zenn 只有預設訊息與 alert 兩種，並非完美的一對一對應。因此要先決定 warn 框歸入一般強調（:::message）還是注意喚起（:::message alert），再統一替換。
語法差異若不想逐一手動比對，可以將本文貼入 Qiita / Zenn 相容性檢查器，與 74 條語法差異規則進行對照。其中一對一決定的 37 條會立即轉換，需要判斷的 14 條可指定替換方式，不支援的 23 條則以提示方式告知。所有處理都在瀏覽器內完成。
特別需要注意的是 Zenn 不會渲染本文中的 raw HTML。Qiita 支援的 <details> 標籤或 <img width="..."> 標籤在 Zenn 上不會產生語法錯誤，而是原樣以標籤字串顯示在本文。同樣道理，寫入 :::message warn 這類不支援的框也不會有容器產生，只會顯示為一行文字。
步驟三：組建 frontmatter 與保留發布日期（published_at）
Zenn 及靜態網站產生器使用檔案開頭的 YAML frontmatter 來管理 metadata（Zenn CLI 指南在新分頁中開啟）。
---
title: "文章標題"
emoji: "📘"
type: "tech"
topics: ["rails", "markdown"]
published: true
published_at: "2023-05-10 09:00"
---
將 Qiita API 回應中的 title 與 tags 對應到這裡。topics 最多可指定 5 個（Zenn CLI 指南在新分頁中開啟），作為檔名的 slug 有限制：英文小寫、數字、連字號、底線的組合，長度 12 至 50 字元（Zenn slug 規格在新分頁中開啟）。
如果要保留過去的發布日期，就在 frontmatter 的 published_at 欄位指定歷史日期（格式為 YYYY-MM-DD 或 YYYY-MM-DD hh:mm，日本時間基準）。Zenn 官方指南也明確指出此欄位可用於從其他平台搬家時保留發布日期。不過，發布日期一旦設定就無法再修改，所以發布前務必確認數值正確。
步驟四：圖片與程式碼區塊後處理
- 圖片 URL：搬家後的文章仍然引用舊平台的圖片 CDN 位址，顯示上沒有問題。但如果原帳號停權或平台政策變更，圖片就會消失。長期要保留的文章，建議把圖片下載到本地，重新上傳到目標平台的儲存空間，並替換本文中的 URL。
- 程式碼區塊：檔名指定語法（
```ruby:qiita.rb）是相容的，但 diff 顯示或特定語法標記的寫法可能因平台而異（例如 Zenn 用```diff js以空格區隔），建議經過渲染預覽確認。
防止重複內容與 canonical URL 設定
文章搬到新平台後，原平台的文章該如何處理？通常有三種選擇：保留原文並在開頭加上「已搬到新部落格」的提示與連結、將原文簡化為摘要與新連結、或刪除原文。搜尋引擎面對同一內容存在於不同 URL 時，會判斷不清哪邊是原始版本；善加利用平台支援的 canonical URL 功能，就能避免重複內容的懲罰。
Dev.to 有 frontmatter 的 canonical_url 欄位可指定原始位址（Dev.to 編輯器指南在新分頁中開啟），Hashnode 在發布流程及 API 中支援原始文章 URL 設定，Medium 則在 URL 匯入功能使用時自動設定 canonical 連結指向原始。
沒有 Markdown 原稿的文章還原（HTML to Markdown）
類似 Medium 的備份檔只提供 HTML，或是過去營運的部落格服務已停擺、只剩網路封存中的 HTML 頁面，這種情況都有。
此時把 HTML 原始碼貼到 HTML to Markdown 即可轉為 GFM 相容的 Markdown。例如以下 HTML 結構：
<h2>安裝與執行</h2>
<p>先執行 <code>npm install</code> 指令。</p>
經過轉換器後會變成乾淨的 Markdown：
## 安裝與執行
先執行 `npm install` 指令。
所有處理都在瀏覽器內部執行，未公開的內部技術文件或私有草稿資料不會殘留在外部伺服器上。
常見問題
平台搬家時能保留原本的發布日期嗎？
取決於目標平台。Markdown 本文本身不包含日期資訊，但支援 frontmatter 的平台中，部分允許指定歷史日期。代表性的例子是 Zenn，透過 published_at 欄位正式支援保留過去的發布日（Zenn CLI 指南在新分頁中開啟）。搬家前請先在原始資料中記錄發布日時。
圖片一定要重新上傳到新平台嗎？
剛搬家完時舊的圖片 URL 仍可正常顯示，但如果原帳號被刪除或平台政策變更，圖片就可能失效。長期要管理的重要技術文章，建議直接下載圖片、上傳到新儲存空間、修改本文中的 URL。
能自動檢查 Qiita 與 Zenn 之間的語法差異嗎？
使用 Qiita / Zenn 相容性檢查器 即可自動對照 74 種語法差異，在瀏覽器中立即查看一對一轉換、需選擇替換、以及不支援語法的提示。
小結
- 部落格搬家的本質就是資料格式的轉換（Markdown、JSON、HTML）。
- 依原始格式不同，流程為：擷取（API、腳本）、語法正規化、frontmatter 重構、圖片與程式碼後處理，共四步驟。
- 沒有 Markdown 原稿的 HTML 備份資料，可透過 HTML to Markdown 在瀏覽器中還原為乾淨的 Markdown。
- Qiita 與 Zenn 間的搬家，善用 Qiita / Zenn 相容性檢查器 預防語法不一致。