この記事では、Zenn CLIを導入し、GitHubリポジトリと連携してZennのコンテンツ（記事や本）を管理する方法を解説します。

以下を参考に実行しましたが、少しハマった点を補足説明します。
GitHub連携

CLI導入

GitHub連携に関しては、手順書通りにやればOKです。
Zenn CLIの導入から解説していきます。
Node.js 14以上がインストールされている必要があります。
2025/10/27追記、Node.js v22.20.0でnpx zenn initを実行するとエラーになる。
参考：https://zenn.dev/porosuke/articles/zenncli-node22-error_porosuke
原因は、Node.js がファイルパスを処理しようとした際に、Windows 環境で Linux/Unix 形式のファイルパスを読み込もうとして失敗していることが原因のようです。
個人的にはNode.jsが対策するのを待ってみようと思い、Node.jsのバージョンを下げたりせず、ZennCLIも使うのをしばらくやめてみようと思っています。

気を付ける点（ハマった点）
・git initを実行する場所はnpx zenn initを実行したところのディレクトリと同じ場所です。
・npx zenn new～も同じ場所です。
・GitHubにpushする前にブランチをmasterからmainに変更してください。

Zenn CLIの導入とセットアップ

まず、ローカル環境でZennのコンテンツを管理するための準備をします。

1. 作業ディレクトリの作成と初期化

.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