👣

Zenn CLIで環境構築から記事公開まで

2025/12/17に公開

この記事でできるようになること

Zenn CLIの環境構築
ローカルでの記事作成・プレビュー
GitHubと連携した記事公開
よくあるトラブルの解決

はじめに

「いつものVS Codeで、Git管理しながら記事を書きたい」

そう思うエンジニアの方は多いのではないでしょうか。

筆者自身も環境構築の中でいくつか「おや？」と止まった箇所がありました。本記事では、初心者がつまずきやすいポイントを押さえながら、最短ルートで執筆環境を整える方法を解説します。

Zenn CLIとは

Zennの記事をローカル環境で作成・管理するためのツールです。

VS Codeなど使い慣れたエディタで執筆できる
Gitでバージョン管理ができる
ローカルでプレビューしながら書ける
GitHubにpushするだけで公開できる

環境構築の全体像

Node.jsのインストール
GitHubリポジトリの作成
リポジトリをローカルにクローン
Zenn CLIのインストール・初期化
ZennとGitHubの連携

Step 1：Node.jsのインストール

Zenn CLIはNode.js上で動作します。v14以上が必要です。

node -v

バージョンが表示されればOK。未インストールの場合は公式サイトからLTS版を導入してください。

Step 2：GitHubリポジトリの作成

Zenn用のリポジトリをGitHubで作成します。

GitHubで「New repository」を選択
リポジトリ名を入力（例：zenn-content）
「Create repository」をクリック

Step 3：リポジトリをローカルにクローン

cd ~/Desktop  # 任意の場所に移動
git clone https://github.com/あなたのユーザー名/zenn-content.git
cd zenn-content

Sourcetree等のGUIツールでクローンしてもOKです。

Step 4：Zenn CLIのインストール

クローンしたディレクトリ内で以下を実行します。

# 1. プロジェクト管理用の設定ファイル（package.json）を作成
npm init --yes

# 2. Zenn CLI本体をインストール
npm install zenn-cli

# 3. Zennに必要なディレクトリ（articles/books）を自動生成
npx zenn init

実行後、ディレクトリ構成は以下のようになります。

zenn-content/
├── articles/      # 記事を入れるディレクトリ
├── books/         # 本を入れるディレクトリ
├── .gitignore     # node_modules等を除外する設定（自動生成）
├── package.json
└── README.md

プレビューの起動

npx zenn preview

ブラウザで http://localhost:8000 にアクセスするとZenn Editorが表示されます。

Step 5：ZennとGitHubの連携

Zennのダッシュボードからリポジトリを連携します。完了後、GitHubへpushするだけで記事が自動反映されるようになります。

記事の作成方法

新規作成

npx zenn new:article

articles/ 内にマークダウンファイルが生成されます。

記事ファイルの構成

---
title: ""
emoji: "😸"
type: "tech"
topics: []
published: false
---

ここから本文

上部のフロントマター（Front Matter）で記事の設定を行います。

項目	説明	例
title	記事タイトル	"Zenn CLIの使い方"
emoji	アイキャッチ絵文字（1文字）	"📝"
type	記事種別	`tech` / `idea`
topics	タグ（最大5つ）	["zenn", "nodejs"]
published	公開設定	`true` / `false`

記事の公開

published: true に変更
プレビューで表示崩れがないか確認
GitHubにpush

git add .
git commit -m "記事を追加"
git push

反映まで数分かかることがあります。ダッシュボードでデプロイ状況を確認してください。

公開予約

未来の日時を指定して公開予約も可能です。

---
published: true
published_at: 2025-01-01 09:00
---

よくあるトラブルと解決法

「command not found: nvm」

nvmの設定が読み込まれていません。

# Macの場合、zshシェルに入る
zsh

# または設定を再読み込み
source ~/.zshrc

Node.jsのバージョン警告

npm warn EBADENGINE required: { node: '>=22.0.0' }

最新のzenn-cliはNode 22以上を推奨していますが、v20やv16でも動作します。

プレビューが表示されない

ポートが使用中の可能性があります。

npx zenn preview --port 3000

記事の変更がZennに反映されない

GitHubへのpush後、反映まで数分かかることがあります
ダッシュボードでエラーが出ていないか確認してください

まとめ

環境構築：

Node.jsをインストール
GitHubでリポジトリを作成
ローカルにクローン
npm install zenn-cli → npx zenn init
ZennとGitHubを連携

執筆フロー：

npx zenn new:article で記事作成
npx zenn preview でプレビュー確認
published: true にしてpush

一度環境を整えれば、あとはいつものエディタで書いてpushするだけで完了です。

参考リンク

GitHubで編集を提案