はじめに
こんにちは、ツクリンクでSREエンジニアをやっているida.です。
早速ですが、みなさんテックブログ書いてますか？
ツクリンクでも2024年10月からZennで本格的にテックブログを始めて、積極的にアウトプットする習慣が今年から根付きつつあります。
ZennではWeb上でエディターが用意されており、初めの頃は皆さんこちらで執筆を始めると思います。しかし、既にご存知の方もいらっしゃると思いますが、GitHubリポジトリと連携することでローカルエディターでの執筆も可能になっています。
僕もZennでのアウトプットを行いながら、より効率的にアウトプットするためにGitHub連携してみたら生産性が上がったので、やり方やメリットを共有したいと思います。
ZennとGitHubを連携する
Zenn公式が手順を公開していますので、シンプルに設定したいという方はこちらを参考にしてみてください。
1. GitHubリポジトリ作成
ご自身のGitHubアカウントでZenn用のリポジトリを作成します。
個人で活用する場合はPublic設定でも良いと思いますが、Publicationへの投稿があったりするとレビュー前に機密情報をPublicリポジトリに公開してしまう懸念があるので、Privateリポジトリを推奨します。
2. publishブランチを作成する
ここは個人的に工夫しているポイントです。mainブランチのままでいいという方はスキップしていただいて構いません。Zennに記事を反映させるには、Zennで指定したブランチへのpushをトリガーに行われ、デフォルトはmainになると思います。開発をしている人なら多くの方がmainに直接pushすることは違和感があると思いますし、反映後にちょっと変更したいとなるとmainへのpushも頻繁に行う必要があります。
これを解決するためにpublishブランチを作成して、Zennにはpublishへのpushで反映するようにしています。git-flow運用でいうところのdevelopブランチの使い方に似ていますね。
（無事レビューが通って公開できたら、後でPR作成してmainにマージするようにしています。）
3. Zennのダッシュボードから連携する
ZennのWebダッシュボード上のGitHubからのデプロイ画面からGitHubリポジトリと連携します。
この時点ではまだブランチを指定しません。
4. 同期するブランチ名をpublishに変更する
リポジトリ設定タブでデプロイ対象ブランチがmainになっていると思うので、publishに変更します。
5. ローカルセットアップ1（リポジトリのcloneの作成）
作成したリポジトリをcloneして、ローカルとGitHubを連携できるようにします。
$ git clone https://github.com/account-name/zenn-xxxxx.git
6. ローカルセットアップ2（Zenn CLIのインストール）
※Node.js 14以上が必要のようなので、インストールされていない場合は事前にインストールしてください。
以下のコマンドでZenn CLIをインストールします。
$ npm init --yes # プロジェクトをデフォルト設定で初期化
$ npm install zenn-cli # zenn-cliを導入
7. ローカルセットアップ3（リポジトリのセットアップ）
cloneしたリポジトリに移動して、以下のコマンドを実行してセットアップします。
$ npx zenn init
README.mdや.gitignoreのほか、articlesとbooksという名前のディレクトリが作成されます。この中にmarkdownファイル（◯◯.md）を入れていくことになります。
以上でセットアップは完了です。
執筆方法
1. 記事の作成
記事の雛形はコマンドで生成できます。
--slugオプションがファイル名となり、公開時のURLパスにもなるので、命名規則はお好みで決めてください。私は以下のような形で作成しています。
npx zenn new:article --slug yyyy-mm-xxxx
2. 記事の執筆
articlesディレクトリ配下にファイルが生成されると思うので、そのファイルに執筆していきます。publicationに公開する場合の雛形のサンプルを以下に記載しておきます。
---
title: "Zennでテックブログ書くときはGitHub連携が便利だよ"
emoji: "🌊"
type: "idea" # tech: 技術記事 / idea: アイデア
topics:
- "ai"
- "Zenn"
- "github"
- "Tech blog"
- "ツクリンク"
published: false
publication_name: "publication名"
published_at: "2025-07-07 00:00"
---
ここから本文を書く
3. 画像の配置
GitHub連携を使用した場合でも、画像はGUIからアップロードして利用できるのですがGitHubでの管理もできるようになります。画像はリポジトリルートのimagesディレクトリに配置します。
# 画像用のディレクトリを作成（日付ディレクトリを作成すると管理しやすい）
$ mkdir -p images/2025-07-02
# 画像ファイルを配置
$ cp screenshot.png images/2025-07/
記事内で画像を使用する際は以下のように記載します：
画像ファイルをimagesディレクトリに配置してGitHubにpushすることで、記事内で画像を参照できるようになります。日付や記事のslugでディレクトリを作成して管理すると、画像の整理がしやすくなります。
ZennをGitHub連携して記事を書くことのメリット
ZennをGitHub連携することによるメリットを自分なりにまとめてみました。
markdownlintやtextlintで記事品質を向上できる
GitHub連携により、VSCodeなどのエディタでmarkdownlintやtextlintといったlinterツールを活用できます。これにより以下のような効果が期待できます：
- markdownlint: Markdown記法の統一性をチェック
- textlint: 日本語表記の統一（ひらがな・カタカナ・漢字の使い分け、敬語表現など）
さらに、huskyと組み合わせることでコミット時にlintを実行し、違反がある場合はエラーで表示してコミットを阻止できます。これにより、品質の低い記事が誤って公開されることを防げます。
これらのツールを導入することで、記事の表記揺れを防ぎ、読みやすい記事を継続的に執筆できるようになります。
CursorやCline等で壁打ちや文章の肉付けができる
最初に大枠や内容を自分で作成した後に、テックブログとしての肉付けや他の記事と平仄を合わせた書き振りに更新してもらうことができます。
また、壁打ちにも使えるので内容のブラッシュアップに利用できます。
これにより書きぶりが統一され、またレビュー時の指摘も少なくなりました。
生成AIへの指示は簡単に以下のようにしていますが、より良いプロンプトがあれば是非教えてください🙏
# 共通ルール
- 日本語でやり取りしてください
- 最初にタスクを実行する計画を作成し、ユーザーの許可を得てから進行してください
- タスクを完遂するために追加で必要な情報がある場合、ユーザーに質問をしてください
- 重要な技術的決定をする場合、簡潔に提示し、ユーザーからのフィードバックを得てください
# Zennブログ 記載ルール
- 同ファイルに過去の記事があるので、`published: true`されている記事を参考に文脈や語尾といった体裁を合わせてください。
ローカルエディタで完結して執筆できる
Web上のエディタで執筆する場合は、ローカルエディタ等で記述して、生成AIに校正してもらい、それをWeb上のエディタに貼り付けて、プレビューを見て...といった流れになると思いますが、ローカルエディタで開発すると、それを全てローカルエディタで実施できます。
少しの手間ですが、継続的に執筆していくなら、この手間がなくなるだけでも大きいです。
URLパスを指定できる
Web上のエディタで執筆した場合、記事のURLが自動採番されたパスになると思います。ローカルエディタで執筆した場合はmdファイルのパスになるので、管理しやすくなります。
以下のようにarticles配下はmdのファイル名になります。
https://zenn.dev/tsukulink/articles/2025-05-execution-environment-using-docker
履歴管理ができる
GitHub管理なので、もちろん履歴管理が可能になります。
注意点
生成AIに記事を生成させて量産させない
大事なことなのでここでも書きますが、ZennはAIに記事を生成させて記事を量産することを禁止しています。 さも正しいかのように誤った記事が乱立すると健全性が損なわれると思うので、用法・用量を守って利用しましょう。
過去の記事は自分でダウンロードしてpushする必要がある
過去にアップロード済みの記事は、自動でZennからGitHubに送られてくるということはありません。
過去の記事もGitHub上で管理したい場合は、以下からZennのエクスポート機能で取得して、自分でpushする必要があります。
ご自身で作成された記事や本のコンテンツは、markdown形式のテキストファイルでエクスポートできます。スクラップはjson形式でダウンロードできます。
エクスポートを行う（要ログイン）
おわりに
ZennとGitHubを連携することで、執筆の効率化と品質向上を図ることができました。特に生成AIとの組み合わせは、校正や平仄合わせにかなり効果的だと感じています。
継続的にテックブログを書いていく予定の方は、ぜひGitHub連携を検討してみてください。皆さんの執筆がより効率的になれば嬉しいです。
Discussion