2025/7/1 ZennとGitHubを連携してみた体験記
この記事では、Zenn CLIを導入し、GitHubリポジトリと連携してZennのコンテンツ（記事や本）を管理する方法を解説します。
以下を参考に実行しましたが、少しハマった点を補足説明します。
GitHub連携
CLI導入
GitHub連携に関しては、手順書通りにやればOKです。
Zenn CLIの導入から解説していきます。
Node.js 14以上がインストールされている必要があります。
気を付ける点（ハマった点）
・git initを実行する場所はnpx zenn initを実行したところのディレクトリと同じ場所です。
・npx zenn new～も同じ場所です。
・GitHubにpushする前にブランチをmasterからmainに変更してください。
Zenn CLIの導入とセットアップ
まず、ローカル環境でZennのコンテンツを管理するための準備をします。
1. 作業ディレクトリの作成と初期化
最終的なディレクトリ構成は以下の通りです。
zenn-books/
|-- .git
|-- package-lock.json
|-- package.json
|-- README.md
|
|-- articles/
| |-- .keep
| |-- how-zenn-github.md
|
|-- books/
| |-- .keep
| |-- e1996bb524c321/
| |-- config.yaml
| |-- example1.md
| |-- example2.md
|
|-- node_modules/
|-- (省略)
.keep という名前のファイルが最初から入っています。 これは Gitが空のディレクトリを認識しない仕様 のため、あえて空であっても「存在させたいディレクトリ」に .keep を入れておくことで、そのディレクトリ構造ごとリポジトリに含めるための小技です。
削除しても問題ありませんが、必要なディレクトリがリポジトリから消えてしまうと、Zenn CLIのコマンドでエラーになることもあるため、なるべく残しておくのが安心です。
それでは実行していきます。
任意の場所に作業用のディレクトリを作成します。
mkdir zenn-books
cd zenn-books
次に、Node.jsのプロジェクトとして初期化し、Zenn CLIをインストールします。
npm init --yes
npm install zenn-cli
2. Zennプロジェクトのセットアップ
以下のコマンドを実行して、Zennのコンテンツ管理に必要なファイルとディレクトリを生成します。
npx zenn init
このコマンドにより、articles（記事用）とbooks（本用）のディレクトリ、および設定ファイルが作成されます。
Gitリポジトリの準備とGitHubへのプッシュ
次に、作成したZennプロジェクトをGitで管理し、GitHubにプッシュします。
1. Gitの初期化とGitHubリポジトリの登録
ローカルでGitリポジトリを初期化します。
git initを実行する場所はnpx zenn initを実行したところのディレクトリと同じ場所です。
git init
GitHubで新しいリポジトリ（例: zenn-content）を作成し、リモートリポジトリとして登録します。【ユーザー名】の部分はご自身のGitHubユーザー名に置き換えてください。
SSH接続、Git Credential Manager (GCM) 、GitHub CLIを使った認証を使っている場合
git remote add origin https://github.com/【ユーザー名】/zenn-content.git
トークン埋め込み型の場合
git remote add origin https://<トークン>@github.com/<ユーザー名>/<リポジトリ名>.git
こちらも参考にしてください。
2. 最初のコミットとプッシュ
生成されたファイルをステージングし、コミットします。
git add .
git commit -m "Zennプロジェクトの初期セットアップ"
デフォルトのブランチ名をmainに変更し、GitHubにプッシュします。
git branch -M main
git push -u origin main
ZennとGitHubリポジトリの連携
最後に、Zennのダッシュボードで今作成したGitHubリポジトリを連携させます。
- ZennのGitHub連携ページにアクセスします。
- 「リポジトリを連携する」ボタンをクリックします。
- 「Only select repositories」にチェックを入れて先ほど作成したリポジトリ（
zenn-content）を選択してinstall&authorizeをクリックします。
これで、ローカルで作成・編集した記事をGitHubリポジトリのmainブランチにプッシュするだけで、自動的にZennにコンテンツが公開・更新されるようになります。
コンテンツの作成とプレビュー
新しい記事の作成
新しい記事を作成するには、ルートディレクトリで以下のコマンドを実行します。
記事のslugを指定する場合は以下のようにします。
npx zenn new:article --slug ここにスラッグ
例：
npx zenn new:article --slug how-zenn-github
実行する位置に気をつけてください。
〇 \zenn-books> npx zenn new:article --slug how-zenn-github
× \zenn-books\articles> npx zenn new:article --slug how-zenn-github
articlesディレクトリに例：how-zenn-github.mdというファイルが作成されるので、これを編集して記事を執筆します。
slugはurlの最後の部分になります。実際のこの記事のURLは、https://zenn.dev/sosa/articles/how-zenn-github
新しい本の作成
本のslugを指定する場合は以下のようにします。
npx zenn new:book --slug ここにスラッグ
この例では --slug オプションを指定していません。その場合、Zenn CLIが内部的に一意の識別子（例：e1996bb524c321）を自動生成し、books/ ディレクトリの下にサブディレクトリ名として使用します。これがその本のスラッグ（URLの一部）になります。
実行する位置に気をつけてください。
〇 \zenn-books> npx zenn new:book
× \zenn-books\books> npx zenn new:book
ローカルでのプレビュー
執筆中の記事や本の表示を確認するには、以下のコマンドを実行します。
npx zenn preview
ブラウザで http://localhost:8000 が開き、リアルタイムでプレビューが表示されます。
CTRL+Cで停止。
記事や本の書き方は、こちらを参照してください。
完成したらコミットとプッシュすれば自動で反映されます。
注意
ZennでGitHub連携している場合、Web上で編集した内容は一時的なものであり、GitHubからのデプロイによって上書きされるという仕様になっています。
⚠️ 状況の整理
1. Webで編集した
- ZennのWebエディタで記事を修正した（例：
how-zenn-github.md）
2. GitHubで別のファイルをコミット・プッシュした
- ただし、Webで修正したファイルはGitHub側では未更新
3. その後GitHubからデプロイが走った
- GitHubから
articles/how-zenn-github.mdが再デプロイされると、Webでの編集内容は上書きされて消える
🛡 対策・おすすめの運用
| 方法 | 説明 |
|---|---|
| ✅ 編集は基本的にローカルで行い、GitHubにプッシュ | 安定したバージョン管理ができる |
| ✅ Webで編集した内容をローカルにコピーしておく | GitHubに反映させたい場合は、手動でローカルに反映してコミットする |
| ✅ 毎回やり直す | GitHub連携を解除してGitHubにあるリポジトリを削除。新しい本や記事のリポジトリを連携 |
💡補足
ZennのWebエディタは便利ですが、GitHub連携をしている場合は「GitHubが正」とみなされるため、Web編集はあくまで一時的なものと考えるのが安全です。
まとめ
| ステップ | 内容 |
|---|---|
| 1 |
npm install zenn-cli でCLIをインストール |
| 2 |
npx zenn init でプロジェクトをセットアップ |
| 3 | GitHubリポジトリを作成し、ローカルと連携 |
| 4 |
npx zenn new:article で記事を作成 |
| 5 |
npx zenn preview で内容を確認 |
| 6 | GitHubにプッシュしてZennに自動反映 |
Zenn CLIとGitHub連携を活用することで、使い慣れたエディタ(例：VS Code)で効率的に執筆活動を進めることができます。
Discussion