💻

Windows11 + WSL + VSCodeで Zenn の執筆環境を構築する

に公開
GitHub
VS Code
Zenn
Windows
WSL
tech

Zenn で技術記事を書いていくために執筆環境を構築しました。
これから同様に環境を整えたい方の参考になるように手順をまとめました。

今回構築する環境は以下のような構成です：

  • OS：Windows 11
  • 仮想環境：WSL2（仮想化機能を有効化）
  • Linux ディストリビューション：Ubuntu
  • エディタ：Visual Studio Code（Remote Development 拡張を使用）
  • 記事管理：Zenn CLI を使ってローカルで執筆・プレビュー
  • バージョン管理：Git + GitHub（毎回のパスワード入力を避けるためSSH接続を使用）

1. UEFI で仮想化機能（Intel VT-x または AMD SVM）を有効にする

WSL2 を使用するには、PC の UEFI（BIOS）で 仮想化機能 を有効にしておく必要があります。
すでに仮想化機能が有効になっている場合は、この手順はスキップして構いません。

仮想化機能が有効かどうかは、タスクマネージャーの［パフォーマンス］タブ > ［CPU］欄の「仮想化：有効／無効」で確認できます。

  1. PC を再起動し、BIOS / UEFI に入ります。
    （一般的には F2 や Del キーを使用しますが、機種によって異なります）。
  2. 仮想化設定（Intel CPUの場合は「Intel VT-x」、AMD CPUの場合は「AMD SVM」）を Enabled（有効） にします。
  3. 設定を保存して再起動します。

2. WSL と Ubuntuディストリビューション をインストールする

PowerShell を管理者権限で開き、以下のコマンドを実行して WSL をインストールします。

wsl --install

このコマンドを実行すると、WSL のインストールに加えて、Ubuntuディストリビューションも自動的にインストールされます。

他の Linux ディストリビューション（Debian、openSUSE など）を後で選びたい場合は、以下のように --no-distribution オプションを指定することで、WSL のみをインストールし、ディストリビューションは後から選んでインストールすることもできます。

wsl --install --no-distribution

インストール後、WSL の状態を確認するには以下のコマンドを使用します。

wsl -l -v

3. Ubuntu ディストリビューションに入る

WSL のセットアップ後、Ubuntu ディストリビューションに入るには、PowerShell で以下のコマンドを実行します。

wsl

これで Ubuntu のターミナルが起動し、Linux 環境で作業ができるようになります。

初回起動時は、以下のようにユーザー名とパスワードの設定が求められます。

  • 任意のユーザー名（半角英数字）を入力
  • 続いて、そのユーザーのパスワードを設定（確認のため2回入力）

※このユーザーは Ubuntu 内での管理者（sudo）権限を持つアカウントになります。

4. Node.js をインストールする

Zenn CLI は Node.jsで動作するため、UbuntuディストリビューションにNode.jsとnpmをインストールします。

sudo apt update
sudo apt install -y nodejs npm

5. ローカルに Zenn 記事用ディレクトリを作成する

UbuntuディストリビューションにZenn 記事を格納するディレクトリを作成して、そのディレクトリに移動します。

mkdir -p ~/repos/zenn-contents
cd ~/repos/zenn-contents

Zenn CLI をインストールします。

npm init --yes
npm install zenn-cli

Zennプロジェクトを作成します。

npx zenn init

README.mdや.gitignoreの他、記事を格納するディレクトリであるarticlesとbooksが作成されます。

詳しくは Zenn 公式ドキュメントもご覧ください：
Zenn 公式ドキュメント「Zenn CLIをインストールする」

6. GitHub に Zenn 用リポジトリを作成して、ローカルリポジトリとリモートリポジトリを同期する

Zenn 記事を GitHub で管理するために、GitHubリポジトリの準備と SSH 接続を行います。

SSH 鍵を作成します。

ssh-keygen -t ed25519 -C "your-email@example.com"

公開鍵の内容を確認してコピーします。

cat ~/.ssh/id_ed25519.pub

GitHub にログインして SSH 鍵を登録します。

  • 右上のプロフィールアイコン →［Settings（設定）］をクリックします。
  • 左メニューから［SSH and GPG keys］を選択します。
  • ［New SSH key］ボタンをクリックします。
    • Title：わかりやすい名前（例：WSL Ubuntu）を入力します。
    • Key：先ほど表示した公開鍵の内容を貼り付けます。
  • ［Add SSH key］をクリックします。

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

  • ホーム画面右上の［＋］→［New repository］をクリックします。
  • Repository name：zenn-contents と入力します。
  • 公開設定はPrivateにします。
  • ［Initialize this repository with:］のチェックはすべて外します。
  • ［Create repository］ボタンをクリックします。

作成後、表示される SSH アドレスをコピーします。

git@github.com:your-name/zenn-contents.git

Zenn 記事用ディレクトリを Git リポジトリにします。

cd ~/repos/zenn-contents
git init

Git のユーザー名とメールアドレスを設定します。

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

ファイルをコミットします。

git add .
git commit -m "Initial commit for Zenn articles"

リモートリポジトリ(GitHub) に同期します。

git remote add origin git@github.com:your-name/zenn-contents.git
git branch -M main
git push -u origin main

これで、Zenn 用のプロジェクトが GitHub 上で SSH 経由で安全に、かつパスワードレスで 管理できるようになります。

7. Zenn と GitHub リポジトリを連携する

Zenn にログインして GitHub の連携設定を行います。

  1. Zenn にログインし、右上のプロフィールアイコン →［GitHubからのデプロイ］をクリックします。
  2. 左メニューから［GitHub連携］を選択します。
  3. ［リポジトリを連携する］ボタンをクリックします。
  4. ［Only select repositories］にチェックを入れます。
  5. 表示されたリポジトリ一覧から、Zenn用に作成したGitHubリポジトリを選択します。

詳しくは Zenn 公式ドキュメントもご覧ください：
Zenn 公式ドキュメント「アカウントにGitHubリポジトリを連携してZennのコンテンツを管理する」

8. VSCode をインストールする

Windows に VSCode をインストールし、Remote Development 拡張機能をインストールします。
（WSLのみを使う場合は［Remote - WSL］拡張機能だけで十分です。SSHやDockerコンテナも扱いたい場合は、全部入りの［Remote Development］をインストールすると便利です。）

9. 記事を書く

  1. Windows で Visual Studio Code を起動します。
  2. 左のサイドバーにある［Remote Explorer（リモートエクスプローラー）］アイコンをクリックします（電源プラグのようなアイコン）。
  3. 表示された［WSL ターゲット］一覧から Ubuntu を指定して開き、Zenn プロジェクトのディレクトリ ~/repos/zenn-contents を開きます。
  4. VSCode のエクスプローラーで articles/ ディレクトリを右クリックし、［New File］ をクリックします。
  5. ファイル名を test-article.md として作成します。

作成した test-article.md ファイルを開いて、以下のような内容を記述します：

---
title: "テスト記事"
emoji: "📝"
type: "tech"
topics: ["zenn", "wsl", "vscode"]
published: false
---

この記事はテスト用の記事です。  
Windows 上の VSCode から WSL の Zenn プロジェクトを編集しています。

published: false としておくと、Zenn 上では下書きとして扱われます。

ターミナルを開き、プロジェクトルート（~/repos/zenn-contents）で以下を実行します。

npx zenn preview

ブラウザで http://localhost:8000 を開くと、Zenn の見た目で記事を確認できます。

編集が終わったら、以下のコマンドで GitHub に反映させます：

git add articles/test-article.md
git commit -m "Add test article"
git push

GitHub に反映されると自動的にZennの記事が更新されます。

Discussion