Zenn で記事を作成する際、「ブラウザ上のエディター」と「ローカル環境のエディター（Zenn CLI が必要）」の2つを利用できます。
おそらく、Zenn のサイト上ですぐに記事が書ける「ブラウザ上のエディター」を利用する方が多いかと思います。
一方で、「ローカル環境のエディター」には以下の様な利点があります。
-
GitHub 連携
- バージョン管理可能
- 校正時に diff を見れて便利
- 記事のテキストや画像を Zenn ではなく自分のリポジトリに保管可能
-
好きなエディターが使える
- 筆者の場合は VSCode を使用しています
- Linter、AI による入力補助など、エディターの機能が利用可能
本記事では、私が普段利用している Zenn 執筆環境の構築方法を紹介します。
- Zenn CLI ローカル環境での記事作成に興味がある方
- Nix での環境構築の簡単さを見てみたい方
- パッケージマネージャとして使いやすいのでお勧め
- 使ってみたいと思った方は分かりやすい解説本があるので是非ご一読ください
- Windows 環境、VSCode 環境の方
- 別環境の方でも、Zenn 独自のルールと対処法を紹介するので参考になるかも？
- Windows 11
- WSL2
- エディター VSCode
- Profile 機能で Zenn 専用のユーザー設定を構築
- .vscode で設定やタスクを管理
- 環境構築 Nix
- Zenn 専用のツール（Zenn CLI）を管理
- ユーザー環境の管理 home-manager
- 汎用的なツール（git など）を管理
フォルダ構成
フォルダ構成
zenn_contents/
├─ articles/
│ └─ 007bff63247432.md
├─ books/
├─ images/
│ └─ 007bff63247432/
│ └─ 007bff63247432-2025-8-25_1.webp
├─ .git/
├─ .gitignore
├─ .vscode/ // VSCode の設定ファイルを配置
│ ├─ settings.json // 拡張の設定を記述
│ └─ tasks.json // タスクを記述
├─ flake.nix // Nix でどのツールを使うかを定義
└─ .envrc // Nix の環境を自動起動するのに使用
最初に Zenn の記事をローカル作成するのに必要なツールを準備します。
その後、VSCode での記事作成の利便性を上げる各種設定を行います。
以下の公式解説記事を参考に、リポジトリの作成と連携を実施します。
2.1 Nix で Zenn CLI 用の開発環境を構築する
以下の様に flake.nix を作成します。
フォルダ構成
zenn_contents/
├─ articles/
├─ books/
├─ images/
+ └─ flake.nix
flake.nix
{
description = "Zenn CLI environment";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
flake-utils.url = "github:numtide/flake-utils";
};
outputs =
{ nixpkgs, flake-utils, ... }:
flake-utils.lib.eachDefaultSystem (
system:
let
pkgs = nixpkgs.legacyPackages.${system};
in
{
devShells.default = pkgs.mkShell {
packages = [ pkgs.zenn-cli ];
};
}
);
}
2.2 環境の立ち上げ
nix develop で flake.nix に基づいて環境が構築されます。
Bash
$ zenn --version
zenn: command not found
$ nix develop
$ zenn --version
0.2.1
$ exit
3.1 home-manager で必要ツールを導入
Zenn 用の環境を開くたびに nix develop を実行するのは手間なので、direnv、nix-direnv で自動化します。
direnv、nix-direnv は flake.nix に基づく環境構築に使用するため、flake.nix に記述する以外の方法でインストールする必要があります。
私は home-manager で WSL の Ubuntu のユーザー環境に導入するツールを管理しています。
home-manager で direnv、nix-direnv を導入する場合は、以下の様に home.nix へ記述します。
home.nix
{ config, pkgs, ... }:
{
home.username = "ryu";
home.homeDirectory = "/home/ryu";
home.stateVersion = "25.05";
home.packages = with pkgs; [
git
bash
direnv
nix-direnv
];
home.file = {
".gitconfig".source = git/.gitconfig;
".bashrc".source = bash/.bashrc;
".profile".source = bash/.profile;
};
programs.home-manager.enable = true;
}
home-manager の利用方法は以下をご参照ください。
本記事では割愛します。
3.2 direnv の設定
以下の様に .envrc を作成します。
フォルダ構成
zenn_contents/
├─ articles/
├─ books/
├─ images/
├─ flake.nix
+ └─ .envrc
zenn_contents に移動してから、direnv allow を実行します。
Bash
cd your_path/zenn_contents
direnv allow
これで zenn_contents に移動すると自動的に Nix て定義した環境が起動するようになりました。
4.1 Profile で Zenn 用の環境を定義
Profile 機能を使用すると、拡張や設定などを一括で定義でき、特定の用途に特化した環境を簡単に作成できます。
4.1.1 設定画面を開く
ファイル > ユーザー設定 > プロファイル > プロファイル をクリックし、プロファイル設定画面を開きます。
4.1.2 プロファイル作成
新しいプロファイルを選択し、名前欄に「Zenn（任意）」と入力し、作成を押します。
4.1.3 プロファイルを開く
ファイル > ユーザー設定 > プロファイル を見ると、既定以外に先ほど作成したプロファイルが選択可能になっています。
私は Zenn という名前を付けています。Zenn をクリックすると、現在開いているワークスペースでは Zenn プロファイルを使用すると VSCode が記憶してくれます。
4.1.4 カスタマイズする
プロファイル作成直後だと、拡張機能や設定がまっさらな状態になっているはずです。
この状態で新しい拡張をインストールした場合、他の環境（既定プロファイルが適用されているワークスペース）にはインストールされません。
これにより、Zenn でしか使わない拡張を入れても他の環境を汚さずに済みます。
この挙動は、設定やキーボードショートカットも同様です。
（便利！）
また、全てのプロファイルで適用する拡張・設定などを指定する機能もあります。
詳細は下記をご参照してください。
今回紹介する便利機能で使用する拡張は以下の通りです。
（拡張の設定・利用方法は次項以降で解説します）
extensions.json
{
"recommendations": [
"mkhl.direnv",
"nodamushi.udon",
"negokaz.zenn-editor"
]
}
4.2 エクスプローラー表示改善・プレビュー機能
Zenn Editor 拡張を利用します。
4.2.1 エクスプローラー表示
通常だと、記事のファイル名は 007bff63247432.md のように Slug で管理されており、何がどの記事かさっぱり分かりません。
拡張により、タイトルが表示されるようになります。
4.2.2 プレビュー機能
通常だと、Zenn CLI の「ブラウザ上でのプレビュー機能」を利用して記事のチェックをします。
Zenn Editor 拡張により、VSCode にてプレビューが可能になります。
4.3 画像リンクのパスを Zenn 仕様に自動変換
Zenn の仕様として、画像の取り扱いには以下のルールが定められています。
- 画像ファイルはリポジトリ直下の /images ディレクトリに配置
- 画像ファイルへのパスは
と記述する
楽に記事へ画像を挿入するために、Udon 拡張を利用します。
他の方法（拡張）でもいいんじゃないの？
色々試した結果、WSL 環境だと Udon 拡張がベストでした。
検討過程が気になる方はこちらをご覧ください。
4.3.1 拡張の設定
以下の様に settings.json へ記述します。
フォルダ構成
zenn_contents/
├─ articles/
├─ books/
├─ images/
├─ flake.nix
├─ .envrc
+ └─ .vscode/
+ └─ settings.json
settings.json
{
"udon.baseDirectories": [
["articles/*.md", "${workspaceFolder}/images/$fileBasenameNoExtension"]
],
"udon.rule": [
["articles/*.md", ""],
["*.md", ""],
["*", "${relImage:${workspaceFolder}}"]
]
}
4.3.2 使い方
Ctrl + Alt + V を押す事で、以下の様に画像を挿入することが可能になります。
007bff63247432.md
`Ctrl + Alt + V` を押すと画像が挿入できる。
フォルダ構成
zenn_contents/
├─ articles/
│ └─ 007bff63247432.md
└─ images/
└─ 007bff63247432/
├─ 007bff63247432-2025-8-25.webp
├─ 007bff63247432-2025-8-25_1.webp
+ └─ 007bff63247432-2025-8-25_2.webp
Windows の場合、Windows キー + shift + s でスクリーンショットを取り、クリップボードへ保存できます。
この状態で、記事（.md ファイル）に Ctrl + Alt + V で張り付けると、画像ファイルの作成・保存・リンクの設定が一括で完了して楽です。
4.4 ブラウザでのプレビューを自動起動
Zenn CLI の機能でブラウザでプレビューすることが可能です。
具体的には、以下の様な手順となります。
- ターミナルで
zenn previewを実行 localhost:8000をブラウザで開く
VSCode で Zenn 用の環境を開くたびに zenn preview を実行するのは面倒です。
そこで、VSCode のタスク機能を利用します。
4.4.1 タスクの設定
以下の様に tasks.json に記述します。
フォルダ構成
zenn_contents/
├─ articles/
├─ books/
├─ images/
├─ flake.nix
├─ .envrc
└─ .vscode/
├─ settings.json
+ └─ tasks.json
tasks.json
{
"version": "2.0.0",
"tasks": [
{
"label": "auto-run my command",
"type": "shell",
"command": "zenn preview",
"isBackground": true,
"presentation": {
"reveal": "never",
"panel": "new",
"focus": false
},
"runOptions": { "runOn": "folderOpen" }
}
]
}
4.4.2 動作確認
VSCode を閉じて、再度 Zenn 用のワークスペースを開きます。
すると、auto-run my command にて zenn preview が自動的に実行されています。
localhost:8000 をブラウザで開くと、記事をプレビューできます。
参考までに、いつもの記事作成ルーティンを紹介しつつ、本記事で扱った各機能の使い方を振り返ってみます。
記事のネタを大まかに表す名前でブランチを作成します。
Bash
git checkout -b zenn-nix
- 記事ファイルの作成
下記ボタンを押すと記事ファイルを新規作成できます。
スクショ：Windows キー + shift + s
画像貼り付け：Ctrl + Alt + V
- git commit
- チャット AI（e.g. ChatGPT）に全文を渡してレビュー依頼
- 記事の再構成/修正
- 修正が完了したら git commit
- リンターで文章フォーマットを統一
リンターの設定は、時間があったら記事にまとめようと思っています。
- 投稿時間を指定、git commit
published を true にし、published_at に投稿したい日時を記述します。
topic は ブラウザで表示される Zenn 記事のトピックをクリックし、このトピックを指定するには ooo と入力という表記を探します。
記事.md
# 記事を新規作成した直後
---
title: ""
emoji: "😽"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: []
published: false
---
# 投稿時
---
title: "WSL × Nix × VSCode で作る Zenn ローカル執筆環境"
emoji: "💮"
type: "tech" # tech: 技術記事 / idea: アイデア
topics: [nix, direnv, vscode, wsl, zenncli]
published: true
published_at: "2025-08-26 20:00"
---
- git push
- GitHub で PR 作成・main ブランチへマージ
- 記事投稿が確定！
本記事では、Nix、home-manager、direnv、VSCode（プロファイル・拡張・タスク）を組み合わせた、Zenn ローカル執筆環境の構築手順を紹介しました。
この構成により、他プロジェクトやユーザー環境を汚さずに Zenn 専用の拡張や設定を適用できます。
また、画像挿入の自動化や文章校正などエディターの支援も活用しやすくなります。
今までは、Dev Containers で環境を構築していましたが、「Zenn CLI が使える隔離環境」を目的とする場合にコンテナはやや過剰だと感じ、Nix へ切り替えました。
devShells は、Zenn CLI を閉じた環境に留めつつ、既存のツールは活かせるちょうどよい緩さがあるのが便利です。
また、起動も早く設定も簡易です。
本記事が皆様の参考になれば幸いです。
Views: 0
