はじめに

Zenn で記事を作成する際、「ブラウザ上のエディター」と「ローカル環境のエディター（Zenn CLI が必要）」の2つを利用できます。

おそらく、Zenn のサイト上ですぐに記事が書ける「ブラウザ上のエディター」を利用する方が多いかと思います。

一方で、「ローカル環境のエディター」には以下の様な利点があります。

GitHub 連携
- バージョン管理可能
- 校正時に diff を見れて便利
- 記事のテキストや画像を Zenn ではなく自分のリポジトリに保管可能
好きなエディターが使える
- 筆者の場合は VSCode を使用しています
- Linter、AI による入力補助など、エディターの機能が利用可能

本記事では、私が普段利用している Zenn 執筆環境の構築方法を紹介します。

想定読者

Zenn CLI ローカル環境での記事作成に興味がある方
Nix での環境構築の簡単さを見てみたい方
- パッケージマネージャとして使いやすいのでお勧め
- 使ってみたいと思った方は分かりやすい解説本があるので是非ご一読ください
  - Nix入門
  - Nix入門: ハンズオン編
Windows 環境、VSCode 環境の方
- 別環境の方でも、Zenn 独自のルールと対処法を紹介するので参考になるかも？

環境の概要

Windows 11
WSL2
- Ubuntu 22.04.5 LTS
エディター 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 での記事作成の利便性を上げる各種設定を行います。

1. Zenn と GitHub の連携

以下の公式解説記事を参考に、リポジトリの作成と連携を実施します。

2. Zenn CLI の導入

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 CLI が未インストール状態
$ zenn --version
zenn: command not found

# 環境起動
$ nix develop

# Zenn CLI が利用できる！
$ zenn --version
0.2.1

# 環境から抜ける
$ exit

3. Nix 環境を自動起動

3.1 home-manager で必要ツールを導入

Zenn 用の環境を開くたびに nix develop を実行するのは手間なので、direnv、nix-direnv で自動化します。

https://github.com/direnv/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

.envrc

use flake

zenn_contents に移動してから、direnv allow を実行します。

Bash

cd your_path/zenn_contents
direnv allow

これで zenn_contents に移動すると自動的に Nix て定義した環境が起動するようになりました。

4. VSCode の設定

4.1 Profile で Zenn 用の環境を定義

Profile 機能を使用すると、拡張や設定などを一括で定義でき、特定の用途に特化した環境を簡単に作成できます。

Zenn 用の Profile 画面

4.1.1 設定画面を開く

ファイル > ユーザー設定 > プロファイル > プロファイル をクリックし、プロファイル設定画面を開きます。

Profile 設定画面を開く

4.1.2 プロファイル作成

新しいプロファイルを選択し、名前欄に「Zenn（任意）」と入力し、作成を押します。

Zenn 用の Profile を作成

4.1.3 プロファイルを開く

ファイル > ユーザー設定 > プロファイル を見ると、既定以外に先ほど作成したプロファイルが選択可能になっています。

Profile 設定画面を開く

私は 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 で管理されており、何がどの記事かさっぱり分かりません。

Zenn Editor 導入前のエクスプローラー表示画面

拡張により、タイトルが表示されるようになります。

Zenn Editor 導入後のエクスプローラー表示画面

4.2.2 プレビュー機能

通常だと、Zenn CLI の「ブラウザ上でのプレビュー機能」を利用して記事のチェックをします。

Zenn Editor 拡張により、VSCode にてプレビューが可能になります。

Zenn Editor 拡張によるプレビュー画面

4.3 画像リンクのパスを Zenn 仕様に自動変換

Zenn の仕様として、画像の取り扱いには以下のルールが定められています。

画像ファイルはリポジトリ直下の /images ディレクトリに配置
画像ファイルへのパスは ![](/images/~) と記述する

楽に記事へ画像を挿入するために、Udon 拡張を利用します。

他の方法（拡張）でもいいんじゃないの？

色々試した結果、WSL 環境だと Udon 拡張がベストでした。
検討過程が気になる方はこちらをご覧ください。
https://zenn.dev/trifolium/articles/c983fc42a138cf

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", "![](/${relImage:${workspaceFolder}})"],
        ["*.md", "![](${relImage})"],
        ["*", "${relImage:${workspaceFolder}}"]
    ]
}

4.3.2 使い方

Ctrl + Alt + V を押す事で、以下の様に画像を挿入することが可能になります。

007bff63247432.md

`Ctrl + Alt + V` を押すと画像が挿入できる。
![](/images/007bff63247432/007bff63247432-2025-8-25_2.webp)

フォルダ構成

 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 が自動的に実行されています。

起動直後のターミナル

auto-run my command の詳細画面

localhost:8000 をブラウザで開くと、記事をプレビューできます。

ブラウザでの記事プレビュー

雑記普段の記事作成の流れ

参考までに、いつもの記事作成ルーティンを紹介しつつ、本記事で扱った各機能の使い方を振り返ってみます。

git ブランチ作成

記事のネタを大まかに表す名前でブランチを作成します。

Bash

git checkout -b zenn-nix

記事ファイルの作成

下記ボタンを押すと記事ファイルを新規作成できます。

新規記事作成ボタン

記事を書く

スクショ：Windows キー + shift + s
画像貼り付け：Ctrl + Alt + V

git commit
チャット AI（e.g. ChatGPT）に全文を渡してレビュー依頼
記事の再構成/修正
修正が完了したら git commit
リンターで文章フォーマットを統一

リンターの設定は、時間があったら記事にまとめようと思っています。

2025/9/6 追記。
書きました。

投稿時間を指定、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 を閉じた環境に留めつつ、既存のツールは活かせるちょうどよい緩さがあるのが便利です。
また、起動も早く設定も簡易です。

本記事が皆様の参考になれば幸いです。

2025/9/6 追記。
リンターの記事を書きました。
本記事の続きです。

Discussion