✍️

Zenn ↔ GitHub ↔ VS Code連携で実現する快適ローカル執筆環境を構築した話(Windows版)

に公開
Git
GitHub
VS Code
Zenn
Markdown
tech

はじめに

初めての記事として、早速以下の内容をまとめて記事にしてみました！

Zennで記事を書く方法としては、ブラウザ上のWebエディタを使うのが一番手軽だと思います。
しかし、普段から使い慣れたエディタで、Gitを使って記事を管理したいと考えるエンジニアやライターの方は多いのではないでしょうか？

私もその一人で、「どうせやるなら、一番効率的で快適な環境を構築したい！」と思い、以下の3つを連携させた執筆フローを構築してみました。

  1. Zenn: 記事の公開プラットフォーム
  2. GitHub: 記事データのバージョン管理
  3. VSCode: ローカルでの記事執筆

本記事は、**「Zennの記事を、使い慣れたVSCodeで書き、GitHubで管理・公開するまで」**の全手順をまとめたセットアップログです。

同じようにZennでローカル執筆環境を構築したい方の参考になれば幸いです。
先人の方々の知恵に感謝します！

なぜこの構成なのか？ 3つのメリット

Webエディタにも良さはありますが、私が「Zenn + GitHub + VSCode」の構成を選んだ理由は、以下のメリットがあるからです。

  1. バージョン管理（Git）
    記事の変更履歴をすべてGitで管理できます。「あの時の表現に戻したい」が簡単にできますし、ブランチを切って大型記事の草稿を練ることも可能です。
  2. 使い慣れたエディタ（VSCode）
    普段の開発で使っているVSCodeの強力な補完機能、Markdownプレビュー、ショートカットキーをそのまま執筆に活かせます。
  3. オフライン執筆OK
    ローカルで記事を書きためておき、好きなタイミングでgit pushするだけで公開（または下書き保存）が完了します。

構築した環境の全体像

今回構築したワークフローの全体像は以下の通りです。

  1. ローカル（VSCode）: npx zenn previewでZennの表示をリアルタイムプレビューしながら記事を執筆。
  2. ローカル（Git）: 書き上がった記事をgit commit & git push。
  3. GitHub: mainブランチ（など、指定したブランチ）にPushされる。
  4. Zenn: GitHubリポジトリの変更を自動で検知し、published: trueになっている記事を自動で公開（falseなら下書きとして同期）。

ステップ1： GitHub に Zenn 記事管理用のリポジトリを作成する

まずは、Zennの記事データを保存するための「倉庫」をGitHub上に作ります。

  1. GitHub にログインし、New repository を作成します。
  2. リポジトリ名 (例: zenn-contents や my-zenn-articles) を決めます。
  3. Public / Private はどちらでもOKです。Zennはどちらのリポジトリにも連携できます。（記事を公開するまで他人に見られたくない場合は Private がおすすめです！私はPrivate で実装しています）
  4. README.md や .gitignore は、この時点では特に必要ありません。
  5. Create repository ボタンを押して、リポジトリを作成します。
  6. 作成後にTOP画面に表示されている、SSHのURLgit@github.com:<アカウント名>/<リポジトリ名>の情報は後ほどVSCodeの設定の中で利用します。

ステップ2： VSCode と GitHub を連携する

次に、ローカルのVS Codeから、Step 1で作成したGitHubリポジトリにアクセスできるようにします。
すでにVS CodeとGitHubを連携させている方は、このステップは飛ばしてOKです！

私は以下の記事を参考にさせていただきセットアップを行いました！
https://zenn.dev/kd_gamegikenblg/articles/b220e23b0b7ef9

  1. VS Codeを開き、左側のアクティビティバーから「ソース管理」アイコンをクリックします。
  2. 「リポジトリのクローン」をクリックします。
  3. 画面上部にURLを貼り付ける枠が出てくるので、リポジトリのURLgit@github.com:<アカウント名>/<リポジトリ名>を入力します。
  4. ローカルで保存するディレクトリを指定します。
  5. VSCodeのエクスプローラーにGitHubの内容が表示されれば無事に連携が完了です！（この時点でファイルなどはないので中身は空っぽ）

これにより、VS CodeのGUI操作（またはターミナル）から clone, commit, push が可能になります。

ステップ3： Zenn の「GitHub からのデプロイ」機能を設定する

Zenn側で「このGitHubリポジトリを監視してください」という設定を行います。

  1. Zenn にログインし、右上のアイコンをクリックした後に出てくるメニューから「GitHubからのデプロイ」をクリックします。
  2. 遷移後の画面に表示されている「リポジトリを連携する」をクリックします。
  3. 連携するリポジトリとして、Step 1で作成したリポジトリを選択します。
  4. デプロイ対象ブランチを指定します。通常は main (または master) ブランチを指定すればOKです。
  5. 「連携する」ボタンを押します。

これで、指定したブランチ（例: main）に push があるたびに、Zennが自動でその内容を検知し、記事や本をデプロイ（下書きとして反映）してくれるようになります。

ステップ4： Zenn CLI を導入する

いよいよ、ローカルの執筆環境を整えます。
私は以下の記事を参考にさせていただきました！
https://zenn.dev/kuuki/articles/20240609_github_to_zenn_first

  1. クローンしたフォルダを開く VS Codeで、クローンしたフォルダ（zenn-contents など）を開きます。
  2. Zenn CLI の導入 VS Codeのターミナル（Ctrl + @ または Cmd + J）を開き、以下のコマンドを実行します。 (前提: PCに Node.js と npm がインストールされている必要があります) 
# 1. Node.jsプロジェクトとして初期化
npm init -y

# 2. Zenn CLI をインストール
npm install zenn-cli

# 3. Zennの初期セットアップ
npx zenn init

※無事に完了すると以下のようなフォルダやファイルが作成されます。
.
├── articles/   # 記事（.md）
├── books/      # 本（.md）
├── package.json
└── README.md

ステップ5: (動作確認) 執筆から公開までの流れを試す

すべての準備が整いました！ 実際に記事を書き、Zennに反映されるかテストしてみましょう。

1. 記事ファイルの作成
ターミナルで以下のコマンドを実行します。

# 新しい記事ファイルを作成
npx zenn new:article

articles フォルダ内に、xxxxxxxxxx.md のようなユニークな名前のMarkdownファイルが自動で作成されます

2. 執筆 & ローカルプレビュー
ここがZenn CLIの素晴らしい点です。以下のコマンドでローカルプレビューサーバーを起動します。

# 新しい記事ファイルを作成
npx zenn preview

ブラウザで http://localhost:8000 を開くと、Zennのサイトそっくりなプレビュー画面が表示されます。

VS Codeで先ほど作成された .md ファイルを編集して保存するたびに、ブラウザが自動でリロードされ、瞬時に変更が反映されます。

3. GitHub に push して Zenn に反映
記事が（ある程度）書けたら、GitHubに push します。

VS Codeの「ソース管理」タブを使うのが簡単です。

  1. 変更をステージ（+ アイコン）
  2. コミットメッセージ（例: feat: 新記事「〇〇」の下書き追加）を入力
  3. 「コミット」ボタンを押し、続けて「変更の同期 (Sync Changes)」ボタン（または push）を押します。

4. Zenn で確認
push が完了して数十秒ほど待ってから、Zennのダッシュボードを開いてみてください。
「記事の管理」の中に、push した記事が自動で「下書き」として追加されているはずです！

おめでとうございます！ これで執筆ワークフローが完成しました！

あとは、ZennのWebサイト上で最終確認を行い、好きなタイミングで「公開」ボタンを押すだけです。
（ローカルで published: true に設定し git push するだけで 自動公開 されます！）

🎉 このワークフローの "推し" ポイントまとめ

なぜこの面倒なセットアップをするのか？ それは、以下の強力なメリットがあるからです。

  • VSCode で書ける: 補完、スニペット、Vimキーバインドなど、使い慣れたエディタの機能をフル活用できます。
  • Git によるバージョン管理: 「いつ、何を、なぜ変更したか」がすべてGitの履歴に残ります。ブランチを切って大型改修するなども自由自在です。
  • 高速なローカルプレビュー: zenn preview の自動リロードが速く、執筆→確認のサイクルがストレスフリーです。
  • オフライン執筆: ローカルファイルなので、飛行機の中や電波の悪い場所でも記事を書き進められます。

😌 おわりに

今回は、Zenn + GitHub + VS Code + Zenn CLI を連携させた、快適な執筆環境を構築する手順を紹介しました。

一度セットアップしてしまえば、あとは 「① VSCode で書く」→「② push する」→「③ Zenn で公開する」 という非常にスムーズな流れが手に入ります。

少しでも「面白そう！」「効率化できそう！」と思った方は、ぜひこのワークフローを試してみてください。 皆さんの快適な Zenn ライフを応援しています！

↓最後に私のセットアップ後の作業環境(VSCode)の画面を参考までに以下に添付します。

参考にした記事

https://zenn.dev/kd_gamegikenblg/articles/b220e23b0b7ef9
https://zenn.dev/kuuki/articles/20240609_github_to_zenn_first

Discussion