Qiita から Zenn へ記事を移行する全手順｜記法差・frontmatter・画像・公開日の引き継ぎ

Q: 公開日時は引き継げますか

引き継げます。frontmatter の published_at に過去の日時（日本時間）を指定します。設定は一度限りで変更できないため、公開前に値を確認してください（Zenn CLI ガイド）。

Q: 一括で自動化できますか

取得と frontmatter 変換は zenn-importer などで自動化できます。ただしバナー記法の 3 種類から 2 種類への寄せ方や diff・数式の表示は機械的に決められないため、公開前のプレビュー確認は残ります。

Qiita の記事を Zenn に引っ越したい。検索すると個人の移行体験記と移行ツールのリリース告知はたくさん見つかりますが、「何をどの順番でやるか」を最初から最後まで見渡せる手順は意外と散らばっています。この記事では、Qiita から Zenn への移行を 4 つのステップに整理し、つまずきやすい記法差・frontmatter・画像・公開日時の扱いをまとめます。

なお、移行したい記事の Markdown ソースが手元に残っておらず、公開ページの HTML しかない場合（Medium や退会済みブログからの移行など）は、その HTML を HTML to Markdown に貼り付ければブラウザ内で Markdown に戻せます。変換はブラウザ内で完結し、アップロードは発生しません。Qiita から Zenn への移行は両方とも Markdown なのでこの作業は不要です。そのまま読み進めてください。

移行の全体像 — 4 ステップと方法の選び方

移行作業は次の 4 ステップに分解できます。

Qiita から記事を取り出す
Qiita 記法を Zenn 記法に直す
frontmatter を Zenn 形式にする
画像とコードブロックを後処理する

進め方は記事数と好みで選びます。

記事が数本だけなら、Qiita の編集画面から Markdown をコピーして Zenn の Web エディタに貼るのが最短です。ステップ 1 は不要になります。
記事が多く、GitHub での管理に慣れているなら、API で一括取得して Zenn の GitHub リポジトリ連携に載せる方法が確実です。この記事はこのルートを軸に説明します。
コマンド操作を避けたいなら、zenn-importer別タブで開きますや QtoZ別タブで開きますのようなコミュニティ製ツールがステップ 1〜3 を自動化してくれます。ただし記法差と画像の後処理（ステップ 2 と 4 の確認）は結局必要です。

ステップ 1: Qiita から記事を取り出す

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

押さえておくポイントは 3 つです（いずれも公式ドキュメント別タブで開きますに記載があります）。

レスポンスの body フィールドが Markdown ソース、rendered_body が HTML です。移行では body を使います。
per_page の上限は 100 です。100 件を超える場合は page を増やして繰り返し取得します。
利用制限は認証ありで毎時 1,000 リクエスト、認証なしは IP あたり毎時 60 リクエストです。個人の移行なら十分な枠です。

ステップ 2: Qiita 記法を Zenn 記法に直す

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 の 3 種類、Zenn は通常と alert の 2 種類なので、warn をどちらに寄せるかを先に決めてから一括置換します。読者への注意喚起なら alert に、補足の強調なら通常の :::message に寄せる、のように記事のトーンで決めれば十分です。

置換後の本文は、Zenn CLI のプレビューで最終確認するのが確実です。その前段の下書き段階では、Markdown to HTML に貼ると GFM としてのレンダリング結果をブラウザ内ですぐ確認できます。:::message のような Zenn 独自記法は GFM に含まれないためそのまま残りますが、表や見出し・リストの崩れはこの時点で拾えます。

ステップ 3: frontmatter を Zenn 形式にする

Zenn の記事ファイルは冒頭の frontmatter で管理されます。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 の説明別タブで開きます）。元記事とのリンク対応表を作っておくと後の確認が楽になります。

published_at で公開日時を維持する

移行でいちばん惜しまれてきたのが「記事が全部『今日公開』になってしまう」問題でした。古い移行記事では「公開日時は引き継げない」と書かれていることがありますが、現在の Zenn は frontmatter の published_at に過去の日時を指定でき、公式ガイド別タブで開きますも「他のブログサービスなどから記事を移行する際に公開日時を維持したい場合」の用途を明記しています。形式は YYYY-MM-DD または YYYY-MM-DD hh:mm（日本時間）です。

ひとつだけ注意があります。公開日時の指定は一度限りで、設定後は変更できません。Qiita API の created_at から機械的に流し込む場合も、公開前に値が正しいか必ず確認してください。

ステップ 4: 画像とコードブロックを後処理する

Qiita に貼った画像は Qiita 側の画像サーバーにあり、本文はその URL を参照しています。移行した直後の記事も同じ URL を参照し続けるため表示はされますが、画像の実体は自分の管理外に残ったままです。長く残したい記事なら、画像をダウンロードして Zenn 側にアップロードし直し、本文の URL を差し替えておくと安心です。

コードブロックは、ファイル名指定（```ruby:qiita.rb）がそのまま使える一方、diff 表示のような装飾は書き方が異なります（Zenn は ```diff js のように言語をスペース区切りで指定します — Zenn の Markdown 記法一覧別タブで開きます）。diff や数式を使っていた記事は、プレビューでの目視確認をスキップしないでください。

移行後の元記事をどうするか

選択肢は 3 つあります。

Qiita の記事を残し、冒頭に「移行しました」と Zenn へのリンクを書き足す
Qiita 側の本文を要約と移行先リンクだけに書き換える
Qiita の記事を削除する

dev.to には重複公開時に正規 URL を宣言する canonical_url という frontmatter がありますが（dev.to エディタガイド別タブで開きます）、Qiita と Zenn の投稿にはこれに相当する設定が見当たりません。同じ本文を両方に置き続けると検索エンジンがどちらを正とするか判断できないため、残す場合は 1 か 2 のように「どちらが本体か」を読者にも検索エンジンにも分かる形にしておくのが無難です。

5 プラットフォーム比較 — どこから何を取り出せるか

Qiita と Zenn 以外も含め、主要プラットフォームの「記事の取り出し方」を整理しておきます。海外サービスとの行き来を考えるときの地図として使ってください。

プラットフォーム	取り出し方	得られる形式
Qiita	API v2別タブで開きますで取得	Markdown（`body`）と HTML（`rendered_body`）
Zenn	GitHub リポジトリ連携別タブで開きますなら記事 = 手元の Markdown ファイル	Markdown
dev.to	本文が Markdown + frontmatter（エディタガイド別タブで開きます）。API 経由のコミュニティ製エクスポータ別タブで開きますで保存	Markdown
Hashnode	ダッシュボードの一括エクスポートは JSON。記事単位なら URL 末尾に `.md` を付けるだけで Markdown を取得可能（公式 changelog別タブで開きます）	JSON / Markdown
Medium	「Download your information別タブで開きます」で ZIP を受け取る	HTML（Markdown 出力なし）

Markdown をくれるサービス同士なら記法と frontmatter の変換だけで済みます。HTML しかくれないサービスが絡むときは、次のセクションの出番です。

Markdown が残っていない記事を復元する

「移行したいのに Markdown ソースがない」というケースがあります。Medium のエクスポートは HTML の ZIP ですし、退会済みのサービスや古いブログでは公開ページの HTML しか残っていないこともあります。Qiita API の rendered_body（HTML）だけ手元にある、という状況も同じです。

この場合は、HTML を HTML to Markdown に貼り付けて実行すれば、GFM 互換の Markdown に変換できます。たとえば次のような HTML は、

<h2>セットアップ</h2>
<p><code>npm install</code> を実行します。</p>

そのまま次の Markdown になります。

## セットアップ

`npm install` を実行します。

変換はすべてブラウザ内で完結し、記事データがサーバーに送信されることはありません。移行対象のアーカイブには限定共有記事や社内向けの下書きが混ざりがちなので、アップロード型の変換サービスに一括で投げる前に、オンライン変換ツールの安全性の観点だけ確認しておくことをおすすめします。Notion の HTML エクスポートを整形する場合はこちらの手順が同じ考え方で使えます。

よくある質問

公開日時は引き継げますか

引き継げます。frontmatter の published_at に過去の日時（日本時間）を指定します。設定は一度限りで変更できないため、公開前に値を確認してください（Zenn CLI ガイド別タブで開きます）。

画像は移行しないと表示されなくなりますか

移行直後は Qiita の画像 URL を参照したまま表示されます。ただし表示は Qiita 側の配信に依存し続けるため、長期的に残す記事は Zenn 側への再アップロードと URL 差し替えを済ませておくのが安全です。

Zenn から Qiita への逆方向はどうやりますか

Zenn は GitHub 連携なら記事がそのまま手元の Markdown ファイルなので、取り出しは不要です。ステップ 2 の対応表を逆向きに適用し（:::message を :::note に戻すなど）、frontmatter を外して Qiita に貼り付けます。

一括で自動化できますか

取得と frontmatter 変換は zenn-importer別タブで開きますなどで自動化できます。ただしバナー記法の 3 種類から 2 種類への寄せ方や diff・数式の表示は機械的に決められないため、公開前のプレビュー確認は残ります。

まとめ

Qiita から Zenn への移行は、取り出し（API）、記法の正規化（対応表で一括置換）、frontmatter（published_at で公開日時を維持）、画像とコードの後処理、の 4 ステップで完了します。Markdown が残っていない記事が混ざっていたら、HTML を HTML to Markdown でブラウザ内変換すれば同じフローに合流できます。変換後の崩れチェックには Markdown to HTML が使えます。どちらもアップロード不要・無料です。