✍️

Zenn執筆環境をVSCode(WSL)+Gitで構築

に公開
Git
VS Code
Zenn
WSL
Obsidian
tech

前提

「WindowsでZenn CLIが動かないのを解決」にまとめた通り、VSCode (WSL接続) + Git + Zenn CLIを中心としたローカルでの執筆ワークフローを構築できたので、自分の中の整理としてその手順とポイントをまとめます。

本当はWSLではなく、Windows環境でそのままやりたかったのですが、zenn-cli をセットアップしようとした際、ERR_INVALID_FILE_URL_PATH というエラーに延々と悩まされました。Node.jsのバージョンを変えても解決せず、最終的にWSL (Windows Subsystem for Linux) を導入し、そのLinux環境上で zenn-cli を動かすことでようやく解決しました。

そのため、この記事で紹介するワークフローはWSL環境が前提となります。

構築したZenn執筆ワークフロー

最終的に落ち着いたワークフローは以下の通りです。改善の余地はあると思いますが、しばらくはこれで。

  1. アイデア・下書き: Obsidian (Windows / Google Drive Vault)
  2. 清書・画像配置・プレビュー: VSCode (WSL接続 / ローカルGitリポジトリ)
  3. 公開: VSCode (WSL接続 / Git Push)

Step 1: アイデア・下書き (Obsidian)

ここは普段利用しているObsidianを使います。

  • Zenn記事のネタは、普段使いのObsidianのVault（私の場合はGoogle Drive同期）にメモからピックアップします。
  • ある程度まとめる単位が固まったら、下書きを作成。普段からMarkdown形式で書いているのでそんなに書き換えはしない。Obsidianのリンク機能やナレッジベースを活用できるのが利点です。

Step 2: 清書・画像配置・プレビュー (VSCode on WSL)

記事をZenn用に仕上げる工程は、WSLに接続したVSCodeで行います。

1. Zenn用リポジトリを開く

  • VSCodeを起動し、左下の緑色のアイコンから「Connect to WSL」を選択。
  • WSL環境に接続されたVSCodeで、git clone した zenn-contents フォルダを開く (/home/ユーザー名/zenn-contents など)。

2. Markdownファイルの作成とFrontmatter

  • articles フォルダ内に新しい .md ファイルを作成。Obsidian上でほぼできている場合はObsidianの .md ファイルをそのままコピーしてくる。ファイル名はそのままslugにするので、半角英数字小文字ハイフン区切り (例：my-first-post.md) とする。

  • ファイルの一番上に、以下のFrontmatterテンプレートを貼り付け、必要事項を記入。これがZenn記事の設定情報になります。

    articles/my-first-post.md
    ---
title: "ここに記事のタイトルを書く"
slug: unique-article-slug-here # URLになる部分 (半角英数字小文字ハイフン)
type: tech # tech（技術記事） or idea（アイデア・コラム）
emoji: "💡" # 記事一覧で表示されるアイコン
published: false # 公開するまでfalse
topics: ["tag1", "tag2"] # 関連技術タグ (最大5つ)
---

## ここから本文

3. 画像の配置

  • zenn-contents フォルダ直下に images フォルダを作成。
  • 別のエクスプローラーウィンドウでObsidian Vaultなどから画像ファイル（半角英数字小文字ハイフン区切り推奨）をWSLの images フォルダにコピー。
  • .md ファイル内で、ルートからの相対パスで画像を指定します。
    ![画像の説明](/images/my-image-01.webp)
    (articles フォルダから見て ../images/ ではない点に注意！ Zenn CLIのプレビューサーバーのルートが zenn-contents 直下になるため)

4. プレビュー

  • VSCodeのターミナル (WSL) を開き、下記を実行。
$ npx zenn preview
  • http://localhost:8000 をWebブラウザで開き、Zenn上でのプレビューを確認。VSCodeで .md ファイルを保存すると、プレビューも自動で更新される。
  • プレビューが終わったら、ターミナルで Ctrl + C を押してサーバーを停止。

Step 3: 公開 (VSCode on WSL)

記事が完成したら、Gitを使って公開します。

  1. .md ファイルのFrontmatterにある published: を false から true に変更して保存。
  2. VSCodeのターミナル (WSL) で以下のコマンドを実行。
    # WSL環境構築後、初回のみ
$ git config --global user.name "xxxx"
$ git config --global user.email "xxxx@gmail.com"

# 記事更新のタイミングで毎回実施
$ git add . # 変更された.mdファイルと追加された画像をステージング
$ git commit -m "Publish: 記事のタイトルやslugなど" # コミットメッセージは分かりやすく
$ git push # GitHubリポジトリにプッシュ
  3. ZennがGitHubへのプッシュを検知し、自動的に記事が公開されます。

まとめ

VSCode (WSL) + Git + Zenn CLIによるローカル執筆環境を構築しました。

  • 記事と画像をGitでバージョン管理・バックアップできる安心感
  • 使い慣れたVSCodeで開発と執筆をシームレスに行える効率性
  • Zennの全記法に対応した正確なプレビュー

これらのメリットはあるものの、Obsidianとはシームレスといかないので（特に画像パスを変更する必要がある）追々もっとシンプルにしていけたらと思います。

Discussion