📝

VS Code による Zenn 記事の執筆環境構築方法

に公開

はじめに

VS Code で Zenn の記事を執筆する環境の構築方法をまとめました。Zenn CLI と GitHub 連携を使えば、ローカルで執筆しながらバージョン管理もできます。

対象読者: コマンドラインの基本知識があると理解しやすいですが、初心者でも最後まで進められるよう、必要な手順はすべて記載しています。

全体の流れ:
VS Code で記事を書く → GitHub に push する → Zenn が自動で記事を公開する

最初だけセットアップが必要で、2 回目以降は「書いて push するだけ」になります。

クイックスタート(既に環境が整っている場合)

Node.js、Git、VS Code が既にインストールされている場合は、以下のコマンドで素早くセットアップできます。

# プロジェクトディレクトリで実行
npm init --yes
npm install -D zenn-cli
npx zenn init
npx zenn new:article --slug my-article

# Git の初期化
git init

# 初回コミット
git add .
git commit -m "initial commit"

# VS Code から GitHub に公開して、Zenn と連携

詳細な手順は以下の「セットアップ」セクションを参照してください。

Zenn × VS Code のワークフロー

セットアップ後は、以下の 3 ステップで記事を公開できます。

  1. 執筆: 記事を書いて、プレビューで確認
  2. 公開設定: フロントマターを published: true に変更
  3. 反映: コミット&プッシュ

詳細な手順は以下のセクションを参照してください。

セットアップ

以下の環境を準備してください。

事前に準備するもの:

  • Node.js(最新 LTS 版を推奨)
  • VS Code
  • Git

セットアップで導入するもの:

  • Zenn CLI(セットアップ手順内でインストール)

1. 必要な環境の準備

以下のツールをインストールしてください(まだインストールしていない場合)。

インストール後、ターミナルで以下を実行して確認します。

node --version
npm --version
git --version

Git の初期設定(初回のみ):

git config --global user.name "your name"
git config --global user.email "your.email@example.com"

2. プロジェクトディレクトリの作成

記事を管理するプロジェクトディレクトリを作成します。

  1. プロジェクト用のフォルダ(例:Documents、Projectsなど)に新しいフォルダを作成
  2. フォルダ名は任意(例:zenn、zenn-articlesなど)
  3. VS Code を起動して、作成したフォルダを開く(「ファイル」→「フォルダーを開く」)

ターミナルでフォルダに移動する場合は、以下のようにコマンドを実行します。

# Windows の場合(例)
cd Documents\zenn

# Mac/Linux の場合(例)
cd ~/Projects/zenn

3. Zenn CLI のインストール

VS Code の統合ターミナル(「ターミナル」→「新しいターミナル」または Ctrl + `)を開いて、以下のコマンドを実行します。

npm init --yes
npm install -D zenn-cli

npm init --yes は、Zenn CLI をローカル管理するための初期設定です。package.json という設定ファイルが作成されます。

-D オプションは開発用依存としてインストールします。プロジェクトごとに異なるバージョンを使い分けられます。

4. プロジェクトの初期化

以下のコマンドでプロジェクトを初期化します。

npx zenn init

以下のディレクトリ構造が作成されます。

.
├── articles/     # 記事を格納するディレクトリ
└── books/        # 本を格納するディレクトリ

画像を使用する場合は、images/ ディレクトリを手動で作成します。

npx zenn init を実行すると、.gitignore ファイルも自動的に作成されます。生成される .gitignore の内容は以下の通りです。

node_modules
.DS_Store

念のため .gitignore の中身を確認し、OS によって生成される不要なファイルが含まれているか確認しましょう。例えば、Windows を使用している場合は Thumbs.db が含まれていないため、必要に応じて追加してください。

node_modules
.DS_Store
Thumbs.db

5. 新規記事の作成

新規記事を作成します。--slug オプションでスラッグ(URL に使用される識別子)を指定します。

npx zenn new:article --slug <スラッグ名>

--slug を省略するとランダムな文字列が生成されます。内容を表すスラッグを指定するのが良いです。

実例:

Projects\zenn> npx zenn new:article --slug zenn-vscode-writing-guide
created: articles/zenn-vscode-writing-guide.md

--slug zenn-vscode-writing-guide を指定すると、articles/zenn-vscode-writing-guide.md が生成されます。スラッグは記事の URL の一部になります(例:https://zenn.dev/username/articles/zenn-vscode-writing-guide)。

コマンドを実行すると、以下のようなファイルが生成されます。

---
title: ""
emoji: "✨"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: []
published: false
---

このフロントマターを編集して、記事のタイトルや絵文字、トピックなどを設定します。

スラッグの命名規則:

  • 使用可能な文字:半角英小文字(a-z)、半角数字(0-9)、ハイフン(-)、アンダースコア(_)
  • 文字数:12 文字以上(上限は Zenn の仕様を確認)
  • 日本語は使用不可

記事の内容を表す短い英単語を組み合わせて作成します。生成された Markdown ファイルを VS Code で開いて執筆します。

6. Git の初期化と GitHub への公開

コマンドライン操作を最小限に抑え、VS Code の機能で GitHub リポジトリを作成します。

ステップ 1: ローカルでのコミット

プロジェクトフォルダで Git を初期化します。VS Code の統合ターミナルで、プロジェクトフォルダ(zenn や zenn-articles など)にいることを確認してから実行します。

# Gitの初期化(プロジェクトフォルダで実行)
git init

VS Code のソース管理パネルからコミットします。

  1. 左側のアクティビティバーから「ソース管理(枝のアイコン)」を開く
  2. すべてのファイルの横にある「+」ボタンをクリックしてステージング(または「変更をすべてステージ」をクリック)
  3. 上部のメッセージボックスに「initial commit」と入力
  4. 「✓」ボタン(コミット)をクリック

ステップ 2: VS Code から GitHub へ公開

ブラウザを開く必要はありません。VS Code の機能を使います。

  1. ソース管理パネル(左側のアクティビティバーの「ソース管理」アイコン)を開いた状態で、上部に表示される「公開」または「Publish Branch」のリンクをクリック
    • もしくは、ステータスバー(画面下部)に表示される「公開」ボタンをクリック
    • 初回の場合、GitHub への認証を求められることがあります
  2. 公開範囲を選択するメニューが出るので、「Publish to GitHub private repository(非公開)」を選択
    • ※Zenn は Private リポジトリとも連携可能です
  3. アップロードするファイル選択で「OK」を押す

これで GitHub 上にリポジトリが作成され、コードがプッシュされます。初回のみ、GitHub へのログインや認証を求められる場合があります。表示に従ってブラウザで認証してください。

7. Zenn との連携設定(GitHub からの自動デプロイ)

Zenn にログインし、右上のメニューから「GitHub からのデプロイ」を選択します。

  1. 「リポジトリを連携する」をクリック
  2. 先ほど VS Code から作成したリポジトリを選択

以上で自動デプロイの設定は完了です。GitHub リポジトリにプッシュすると、自動的に Zenn に記事が反映されます。

GitHub 連携のメリット: ローカル PC が壊れても、GitHub にプッシュした記事は復元できます。Git を使うことで、バックアップとバージョン管理を同時に実現できます。

連携の確認方法: Zenn のダッシュボードで「GitHub からのデプロイ」を確認すると、連携されているリポジトリとデプロイ履歴が表示されます。初回プッシュ後、数分で記事が反映されます。

デプロイが失敗した場合: Zenn ダッシュボードの「GitHub からのデプロイ」ページで、デプロイ履歴を確認できます。エラーが発生している場合は、エラーメッセージが表示されるので、それを参考に修正してください。よくある原因は、フロントマターの構文エラーや、スラッグの命名規則違反です。

次回以降は、記事を執筆してコミット&プッシュするだけで公開できます。

VS Code での執筆

おすすめの VS Code 拡張機能

執筆に便利な拡張機能です。VS Code の拡張機能パネル(Ctrl + Shift + X)から検索してインストールします。

拡張機能 拡張機能 ID 説明
Zenn Editor negokaz.zenn-editor Zenn 専用の拡張機能。プレビュー表示、画像アップロード、新規記事作成などを VS Code 上で完結できる
Markdown All in One yzhang.markdown-all-in-one キーボードショートカット、目次の自動生成、リストの自動補完など
markdownlint davidanson.vscode-markdownlint Markdown の文法チェック。読みやすい記事を書くのに役立つ
Paste Image mushan.vscode-paste-image クリップボードの画像を直接 Markdown に貼り付け

Zenn Editor は Zenn 特有の記法にも対応しているので、執筆がかなり楽になります。

基本的な使い方

  1. 生成された Markdown ファイルを VS Code で開く
  2. フロントマター(ファイル先頭の---で囲まれた部分)で記事のメタ情報を設定
  3. 本文を Markdown 形式で記述

フロントマターには、記事のタイトル、絵文字、トピック、公開設定などを記述します。

VS Code の Markdown 設定ワンポイント

執筆体験を向上させる設定です。

  • 自動保存 ON 推奨:設定で「自動保存」を有効にしておくと、執筆中にファイルが自動保存されます
  • 見出しジャンプ用アウトライン表示:エクスプローラーパネルで「アウトライン」を表示すると、見出し一覧からジャンプできます

執筆のコツ

  • 見出しは ## から始める(# は Zenn がタイトル用に予約)
  • 1 記事 1 テーマに絞ると読まれやすい
  • コードブロックには言語指定を忘れずに(シンタックスハイライトが効く)

注意: 見出しは ## から始めます。# は Zenn がタイトル用に予約しているため、# から始めるとタイトルが二重表示されることがあります。プレビューで確認しながら書くと、こうしたミスを防げます。

実際の執筆フロー例

以下は、実際に記事を書く際の流れです。

  1. 下書き作成: npx zenn new:article --slug my-first-article で記事を作成
  2. 執筆: VS Code で Markdown を書く(npx zenn preview で確認しながら)
  3. 画像追加: 必要に応じて images/my-first-article/ に画像を配置
  4. 最終確認: ブラウザプレビューで見た目を確認
  5. 公開: published: true に変更してコミット&プッシュ

コツ: プレビューを開いたまま執筆すると、リアルタイムで確認できて便利です。

フロントマターの設定例

---
title: "記事のタイトル"
emoji: "📝"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: ["zenn", "vscode"]
published: false
---

各項目の説明:

  • title: 記事のタイトル(必須)
  • emoji: 記事のサムネイルとして表示される絵文字。一部の特殊な絵文字は正しく表示されない場合があるため、一般的な絵文字を使う
  • type: tech(技術記事)または idea(アイデア記事)を指定
  • topics: 関連するトピックを配列で指定(最大 5 つ)。既存のトピックを使うと検索されやすくなる
  • published: true で公開、false で下書き
  • published_at: (オプション)予約投稿の日時を指定(例:2024-12-25 09:00)

topics の選び方: Zenn には既存のトピック一覧があります。既存のトピックを使うと、そのトピックをフォローしているユーザーのフィードに記事が表示されやすくなります。新しいトピックを作成することもできますが、まずは既存のトピックから選ぶことをおすすめします。

予約投稿

published_at を指定すると、指定した日時に自動的に記事が公開されます。

日時は YYYY-MM-DD HH:MM 形式で指定します。タイムゾーンは JST(日本標準時)です。

---
title: "予約投稿のテスト"
emoji: "⏰"
type: "tech"
topics: ["zenn"]
published: true
published_at: "2026-01-25 09:00"
---

published: true と published_at を両方設定します。指定日時になると自動的に公開されます。

プレビューの確認

執筆中に記事の見た目を確認するには、以下のコマンドを実行します。

npx zenn preview

ブラウザで http://localhost:8000 にアクセスすると、Zenn 上での表示を確認できます。Markdown ファイルを編集すると、ブラウザ上でリアルタイムにプレビューが更新されます。

プレビュー手段の使い分け:

  • VS Code 内プレビュー(Zenn Editor 拡張機能):軽く構文や画像位置を見る用
  • ブラウザプレビュー(npx zenn preview):本番とほぼ同じ見た目を確認する用

ブラウザプレビューの方が本番環境に近いので、公開前の最終確認にはこちらを使うのがおすすめです。

画像の挿入方法

Zenn で画像を使用する方法は 2 つあります。

方法 1: ローカル画像を使用(GitHub リポジトリに含める)

プロジェクト内に images ディレクトリを作成し、そこに画像を配置します。

.
├── articles/
├── books/
└── images/
    └── article-slug/
        └── image01.png

記事内では以下のように参照します。

![代替テキスト](/images/article-slug/image01.png)

注意: VS Code 標準のプレビュー機能では、Zenn の絶対パス形式(/images/...)の画像が表示されない場合があります。画像確認には npx zenn preview を使うのが確実です。

Paste Image 拡張機能を使う場合:

Zenn では画像ファイルを /images ディレクトリに置くルールがあります。Paste Image 拡張機能を使う場合、デフォルト設定のままだと Markdown ファイルと同じ場所に画像が保存されてしまいます。

VS Code の設定(settings.json)または拡張機能の設定画面で、Paste Image: Path を ${projectRoot}/images/${currentFileNameWithoutExt} に設定しておくと、Zenn のディレクトリ構造に合わせて画像が整理されやすくなります。

メリット: 画像も Git で管理でき、外部サービスに依存しない
デメリット: リポジトリのサイズが大きくなる

方法 2: Zenn のアップロード機能を使用

Zenn Editor 拡張機能を使うと、VS Code から直接 Zenn のサーバーに画像をアップロードできます。

  1. Zenn Editor 拡張機能をインストール
  2. 画像をドラッグ&ドロップ、またはクリップボードから貼り付け
  3. 自動的に Zenn にアップロードされ、URL が挿入される
![](https://storage.googleapis.com/zenn-user-upload/xxxxxxxx.png)

メリット: リポジトリのサイズを抑えられる、手軽
デメリット: 外部サービスへの依存

記事の公開

執筆が完了したら、以下の 3 ステップで公開します。

  1. 公開設定: フロントマターで published: false を published: true に変更
  2. コミット: VS Code のソース管理パネルで変更をコミット
  3. プッシュ: 「変更の同期」ボタンをクリック

プッシュすると、数分で Zenn 上に記事が自動的に公開されます。

操作手順は初回セットアップの「ステップ 1: ローカルでのコミット」と同じです。VS Code のソース管理パネルから変更をステージング、コミット、プッシュします。

コマンドラインで実行する場合:

git add .
git commit -m "記事を公開"
git push

記事の更新

公開済みの記事を更新する場合も、同様にコミット&プッシュするだけで反映されます。ただし、以下の点に注意してください。

  • スラッグ(ファイル名)を変更すると URL が変わり、別記事として扱われる
  • 大幅な更新時は、記事末尾に更新履歴を記載すると親切

複数記事を書く場合の運用

記事が増えてきたら、以下の点を意識すると管理しやすくなります。

画像フォルダの分け方: 記事ごとに images/ ディレクトリ内にフォルダを作成します。例えば、images/article-slug-1/、images/article-slug-2/ のように分けると、画像が整理されます。

記事の管理: articles/ ディレクトリ内の Markdown ファイルがそのまま記事になります。ファイル名(スラッグ)で記事を識別するため、分かりやすいスラッグを付けることが重要です。

複数端末で書く場合の注意

別の PC で執筆を続ける場合、まず git pull で最新の状態を取得してから始めます。

git pull

複数端末で同時に編集すると競合が発生する場合があります。競合が起きた場合は、VS Code のソース管理パネルで競合を解決してからコミットします。複数端末で作業する場合は、作業前に必ず git pull する習慣をつけましょう。

よくある初学者ミス

実際によく起きるミスと対処法です。

articles 以外に Markdown ファイルを置いてしまう

Zenn は articles/ ディレクトリ内の Markdown ファイルのみを記事として認識します。プロジェクトのルートや books/ に置いても反映されません。

フロントマターの --- を消してしまう

フロントマターはファイルの先頭と末尾を --- で囲む必要があります。消してしまうと Zenn が記事を認識できません。

published: true にし忘れる

フロントマターで published: false のままプッシュすると、記事は下書きのままです。公開する場合は必ず published: true に変更します。

スラッグに日本語や大文字を使う

スラッグは半角英小文字、数字、ハイフン、アンダースコアのみ使用可能です。日本語や大文字を使うとエラーになります。詳細は「新規記事の作成」セクションのスラッグの命名規則を参照してください。

トラブルシューティング

よくある問題と解決方法です。

npx zenn コマンドが動かない

原因: Node.js がインストールされていない、またはバージョンが古い
解決: node --version でバージョンを確認し、最新 LTS 版に更新します。Zenn CLI は比較的新しい Node.js バージョンを要求するため、最新 LTS 版を使用することを推奨します。

npm 経由でアップデートする場合:

n パッケージを使う方法:

npm install -g n
n lts

nvm を使っている場合:

nvm install --lts
nvm use --lts

上記の方法を使っていない場合: Node.js 公式サイト から最新 LTS 版をダウンロードして再インストールします。

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

原因: ポート 8000 が他のアプリケーションで使用されている
解決: 別のポートを指定して起動

npx zenn preview --port 3000

GitHub にプッシュしても Zenn に反映されない

確認事項:

  1. Zenn とリポジトリが連携されているか(ダッシュボードの「GitHub からのデプロイ」で確認)
  2. デプロイ対象のブランチが正しいか(デフォルトは main)
  3. フロントマターの published: true になっているか
  4. Markdown ファイルの構文エラーがないか(フロントマターの --- が正しく閉じられているか)
  5. デプロイ履歴を確認(Zenn ダッシュボードでエラーが出ていないか確認)

画像が表示されない

確認事項:

  1. 画像パスが正しいか(/images/ から始まる絶対パス)
  2. 画像ファイルがリポジトリにコミットされているか
  3. 画像ファイル名に日本語や特殊文字が含まれていないか

スラッグのエラー

スラッグミスでエラーが出る場面はよくあります。デプロイが失敗したら、まずスラッグを確認してみてください。

原因: スラッグが命名規則に違反している
解決: 「新規記事の作成」セクションのスラッグの命名規則を確認してください。

よく使うコマンド

コマンド 説明
npx zenn new:article --slug xxx 新規記事を作成
npx zenn new:book --slug xxx 新規本を作成
npx zenn preview ローカルプレビューを起動
npx zenn --help ヘルプを表示

メンテナンス

Zenn CLI のアップデート

長く運用していると CLI が古くなるため、定期的に最新版に更新することをおすすめします。

npm install -D zenn-cli@latest

トラブルシューティングで問題が発生した場合も、まず CLI を最新版に更新してみてください。

まとめ

VS Code と Zenn CLI を組み合わせれば、ローカル環境で記事を執筆できます。プレビュー機能や拡張機能を活用して執筆し、GitHub 連携でバージョン管理と公開を一元化できます。

Discussion