🔧

Zennの既存記事をGitHub連携で管理しようとしてハマったこと

に公開
GitHub
Zenn
備忘録
Claude Code
tech

結論

GitHub連携して Claude Code から投稿するのがマジで楽。

ただし、 Zennエディタで作成した既存記事は、GitHub連携では上書きできない。

対処法は2つ：

  1. 新規記事として公開する（別のslugで）
  2. 既存記事を削除してから連携する

これを知らずに何度もデプロイエラーと戦った記録。

この記事について

Claude Code シリーズの番外編として、Zenn × GitHub連携でハマったことをまとめた。

つまずいたこと

1. 既存記事が上書きできない

やりたかったこと：
Zennエディタで書いた記事を、GitHub連携で管理したい。

やったこと：
既存記事のslugをファイル名にして、フロントマターに slug: xxx を追加してpush。

結果：

slug の重複エラー

原因：
Zennエディタで作成した記事と、GitHub連携で作成した記事は 別管理。
同じslugを使おうとすると重複扱いになる。

2. slugの仕組みを知らなかった

やりたかったこと：
わかりやすいファイル名（例：claude-code-tips.md）で管理したい。

やったこと：
フロントマターに slug: f2260aa9006dd3 を追加。

結果：
まだ重複エラー。

原因：
Zennでは ファイル名（拡張子除く）がslugになる。
フロントマターの slug: は無視される場合がある。

3. ファイル名を変えても解決しない

やりたかったこと：
ファイル名を新しいslugに変更して公開。

やったこと：
claude-code-tips.md → claude-code-tips-and-features.md にリネーム。

結果：
まだエラー。

原因：
既存記事（エディタ作成）が残っている限り、同じ内容の記事は重複扱い。
既存記事を削除してからpush する必要があった。

4. 投稿数の上限（レートリミット）

やりたかったこと：
複数の記事をまとめてpushして一気に公開。

やったこと：
3記事以上を同時にpush。

結果：
Zenn管理画面に以下のメッセージが表示された：

次の記事は一定時間以内の投稿数の上限に達したためデプロイされませんでした。しばらく時間をあけてお試しください。

原因：
Zennにはスパム対策として投稿数の上限（レートリミット）が設けられている。

公式情報:

対処法:

  1. 焦ってリトライしない — 逆効果の可能性がある
  2. 24時間程度待つ — 多くの場合、翌日には解除される
  3. 改善しない場合はZennに問い合わせ

予防策:

  • 複数記事の同時公開を避ける（1日1記事を目安に）
  • git force-push ではなく通常の git push を使用
  • 細かい修正は1回のコミットにまとめてからpush

事前に確認すべきだったこと

確認事項 理由
既存記事の作成方法 エディタ作成 vs GitHub連携で挙動が異なる
Zennのslug仕様 ファイル名 = slug という仕様
上書きの可否 エディタ作成記事はGitHub連携では上書き不可
投稿数の上限 複数記事の同時公開でレートリミットに引っかかる可能性

最終的な手順（成功パターン）

Step 1: Zenn CLI セットアップ

cd C:\Users\your-name\Documents\Projects\zenn-articles

# npm初期化
npm init -y

# Zenn CLIインストール
npm install zenn-cli

Step 2: Git 初期化

git init

Step 3: GitHub リポジトリ作成 & push

GitHub CLI を使う場合：

gh repo create zenn-articles --public --source=. --remote=origin --push

手動でやる場合：

  1. https://github.com/new でリポジトリ作成
  2. 以下を実行：
git remote add origin https://github.com/your-name/zenn-articles.git
git branch -M main
git add .
git commit -m "Initial commit"
git push -u origin main

Step 4: Zenn ダッシュボードで連携

  1. https://zenn.dev/dashboard/deploys にアクセス
  2. 「リポジトリを連携する」をクリック
  3. 先ほど作成したリポジトリを選択
  4. 「連携する」をクリック

Step 5: 既存記事がある場合は削除

重要： エディタで作成した既存記事をGitHub連携で管理したい場合、 Zennエディタ側の記事を削除 する。

  1. https://zenn.dev/dashboard にアクセス
  2. 対象記事の「...」メニュー → 「記事を削除」

Step 6: ファイル名をユニークに設定

articles/
  my-first-article.md      ← このファイル名がslugになる
  another-article.md

注意：

  • ファイル名は12〜50文字
  • 半角英数字（a-z, 0-9）とハイフン（-）、アンダースコア（_）のみ
  • わかりやすく、かつユニークな名前にする

Step 7: 公開

# published: true に変更してから
git add .
git commit -m "Publish articles"
git push

GitHub連携 + Claude Code の何が楽か

記事作成

> Zennの記事を書いて。タイトルは「〇〇」で。

→ ファイルが自動で作成される。

公開

> 公開して

→ published: true に変更 → git add → commit → push まで自動。

修正

> この部分、もう少しわかりやすく書き直して

→ 編集 → commit → push まで自動。

Zennエディタとの比較

操作 Zennエディタ GitHub連携 + Claude Code
記事作成 手動で書く 「書いて」で生成
公開 ボタンクリック 「公開して」で完了
修正 手動で編集 「直して」で完了
バージョン管理 なし Git で履歴が残る
複数記事の一括操作 1記事ずつ まとめて操作可能

この記事自体も Claude Code で書いて push した。

学んだこと

学び 詳細
別管理だった Zennエディタで作成した記事とGitHub連携は別管理
今後の方針 新規記事はGitHub連携で管理すると楽
slug仕様 ファイル名 = slug という仕様を覚えておく
レートリミット 複数記事の同時公開は避ける、エラー時は24時間待つ
最強の組み合わせ Claude Code + GitHub連携が最強の執筆環境

まとめ

  • Zennエディタで作成した記事は、GitHub連携では 上書きできない
  • 既存記事をGitHub管理したいなら、 エディタ側を削除してから 連携
  • ファイル名 = slug なので、 わかりやすいユニークな名前 をつける
  • 複数記事の同時公開でレートリミットに注意、エラー時は 24時間待つ
  • Claude Code + GitHub連携 = 「書いて」「公開して」で完結する最強環境

今後の記事はすべてGitHub連携で管理する予定。

GitHubで編集を提案

Discussion