🎉
GitHubリポジトリでZennのコンテンツを管理する方法 (初心者向けガイド)

2024/10/06に公開
Git
 はじめにZenn への執筆を始めるにあたり、将来的な拡張性を考えて、最初から Zenn CLI にトライアルすることにしました。
Zenn CLIは、技術情報共有サービス「Zenn」で記事や本を効率的に作成・管理・公開するためのツールです。ZennにはWeb上のエディターが用意されていますが、GitHubリポジトリと連携すればローカルのテキストエディターで執筆することもできます。
普段、ドキュメントは Markdown形式を使うことが多いのと、最近は Chatgpt などの生成AIを併用してドキュメント化することも多いので、効率を考慮すると、この手段が最も最適解と「直感」しました。それがきっかけです。
組込みエンジニアを長年してきて、最近、IoTに関連する仕事に従事しました。


若いエンジニアの方が、何気なく利用する git も、私たちの old-fashioned な人間からすると使ったことがないツールであり、案の定、github のプッシュ操作で躓いたので(公式ドキュメントには、git の操作は知っててアタリマエの前提で書いているので)、ここでは、手順に迷ったり、止まったりしたところを補完した、初心者向けガイド としてレポートしておこうと思います。


 Zenn CLI について
 利用する目的
効率的なコンテンツ作成: Markdown形式で簡単に記事や本を作成。

リアルタイムプレビュー: ローカル環境でのプレビュー機能により、公開前に内容を確認。

バージョン管理: GitHubとの連携で、記事や本のバージョン管理や共同編集が可能。


 要件
Node.js:
Node.js 14以上が必要です。公式サイトからインストールできます。


GitHubアカウント:
GitHubリポジトリと連携するために必要です。


エディタ:
好きなエディタ（例：VSCode）を使用して記事を編集できます。



 効用
効率的な記事作成:
コマンド一つで新しい記事のテンプレートが生成され、手間が省けます。


リアルタイムプレビュー:
ローカル環境で記事のプレビューが可能で、公開前に内容をしっかりとチェックできます。


GitHubとの連携:
GitHubリポジトリと連携することで、記事や本のバージョン管理が容易になります。複数人での共同編集や差分管理が可能です。


公開予約:
記事の公開日時を指定することができ、指定した日時に自動的に記事が公開されます。


簡単な更新と削除:
記事の更新や削除が簡単に行えます。



 基本原理(仕組み)Node.jsはJavaScriptのランタイム環境であり、サーバーサイドのスクリプトを実行するために使用されます。Zenn CLIはこのランタイム環境上で実行します。これにより、Zennサービス上のプレビュー画面を確認することができます。
GitHubはバージョン管理システム(構成管理ツール)であり、Zenn CLIで作成した記事や本を管理するために使用されます。Zenn CLIで作成したディレクトリを、GitHubリポジトリにプッシュすることで、コンテンツがZennに反映されます。これにより、GitHub上でコンテンツのバージョン管理が行えます。
エディタは、記事や本の内容を編集するために使用されます。Markdown形式を利用するので、私はVSCodeを利用しています。Zenn CLIにより、Zennサービスでコンテンツのタイトルを認識するためのヘッダ形式を含む下書き用の .md ファイルが出力されます。あとはそれに追記するだけ。
編集が完了したら、GitHubリポジトリにプッシュして、Zennに反映させます。
それぞれのツールの連携はまとめると :

Node.js: Zenn CLIの実行環境を提供。

GitHub: コンテンツのバージョン管理とデプロイを担当。

エディタ: コンテンツの編集を行うツール。VSCode。推敲用に生成AIサービス(Chatgpt, Copilot)


 手順Zenn公式 : GitHubリポジトリでZennのコンテンツを管理する の手順に沿って進めます。但し、この手順には github のリポジトリに対する操作は含まれていないので、このガイドで補完します。
手順ステップは、次の通りです :
github に、リモートリポジトリを作成し、Zennサービスと連携する。
リモートリポジトリを、ローカルに「クローン」する。クローン先のフォルダをローカルリポジトリとする。
ローカルリポジトリに、Zenn CLI を利用して必要な環境をセットアップする。
ローカルリポジトリに、コンテンツを作成し、Zenn CLIのプレビューで確認する。
コンテンツの内容を、ローカルリポジトリに「コミット」する。
リモートリポジトリに、ローカルリポジトリの内容を「プッシュ」する
リモートリポジトリが、Zennサービスと連携している場合、自動的にZennサービスへ公開される。
ここで、github のリポジトリについて、軽く理解しておきましょう。リポジトリとは、コンテンツの編集・追加・削除の履歴を記録したデータベースです。これにより、複数の人による同じコンテンツの編集がされても、そのコンテンツをマージし、競合した場合の修正を容易にします。或いは特定のバージョンのコンテンツを取り出すことも出来ます。リポジトリには「リモートリポジトリ」と「ローカルリポジトリ」の二つあり、これらを使い分けて効率的なコンテンツの構成管理と共有をすることができます。
ローカルリポジトリは、自身のコンピュータ上に存在するワークスペースとしてのリポジトリです。ここでコンテンツの編集、追加、削除などの作業を行います。ローカルリポジトリ内での変更は、コミット 操作によって保存されます。
リモートリポジトリは、github のサーバー上に存在するリポジトリです。複数のメンバーとコンテンツを共有したり、バックアップとして利用します。ローカルリポジトリの変更は、プッシュ 操作によってリモートリポジトリに反映されます。リモートリポジトリから、クローン 操作によってローカルリポジトリを作成することが出来ます。
git の操作は GUIベースの GitHub Desktop を利用します。


 1. github に、リモートリポジトリを作成し、Zennサービスと連携する。リモートリポジトリの作成と、Zennサービスへの連携を行います。
Zenn公式 : GitHubリポジトリでZennのコンテンツを管理する の手順に沿って進めてください。
これで、リモートリポジトリが自身のgithubアカウント内に作成され、そのリモートリポジトリがZennサービスに連携されています。


 2. リモートリポジトリを、ローカルに「クローン」する。リモートリポジトリを、ローカルに「クローン」し、ローカルリポジトリを作成します。ここから、GitHub Desktop を使います。

GitHub Desktopの公式サイトにアクセスし、インストーラをダウンロード、インストール。
GitHub Desktopを起動。起動時に自身の github アカウントでサインイン。
「File」メニューから「Clone repository」を選択から、リモートリポジトリを選択し、クローン。


 3. ローカルリポジトリに、Zenn CLI を利用して必要な環境をセットアップする。Node.js command prompt を起動します。Windowsのメニューから選択できます。次に、ローカルリポジトリへ移動します。
Zenn公式 : Zenn CLIをインストールする の手順に沿って進めてください。
全ての手順が終了すると、ローカルリポジトリに以下の内容物が追加されています。


 4. ローカルリポジトリに、コンテンツを作成し、Zenn CLIのプレビューで確認する。ローカルリポジトリのパスで、Node.js command prompt から "npx zenn new:article" を入力します。すると、articleフォルダに新規の .md ファイルが出力されます。ファイル名の初期はランダムな値になっているので、適宜、12文字以上の管理しやすいファイル名に直します。
続いて、プレビュー画面を表示してみましょう。Node.js command prompt から、"npx zenn preview"を入力します。すると、"http://localhost:8000" のようにプレビュー先のURLが表示されるので、出力されたURLをコピーしてブラウザを立ち上げ、このURLを手動入力してアクセスします。ブラウザは自動で立ち上がらないので注意が必要です。
コンテンツは Markdown形式で作成します。一部、Zennの特有のスクリプトも利用できます。画像は、ローカルリポジトリの直下に、「images」フォルダを作成し、そこに配置する必要があります。いずれもプレビュー画面にあるガイドを参考にしてください。


 5. ローカルリポジトリに、コンテンツを「コミット」する。作成したコンテンツを、ローカルリポジトリに「コミット」します。一人で利用している場合は問題ないと思いますが、複数人で同じコンテンツを操作する場合は、この「コミット」操作により変更がマージされます。同じ行を変更した場合は競合のマーキングがされるので、競合した箇所をマニュアルで修正する必要があります。
追加・変更・削除されたコンテンツは、GitHub Desktopのエクスプローラ画面に表示されています。内容に問題なければ、❶サマリーを入力して、❷「commit to main」ボタンを押します。


 6. リモートリポジトリに、ローカルリポジトリの内容を「プッシュ」する。公開するコンテンツが完成したら、ヘッダの記述の"published"を true に変更します。
---
title: "GitHubリポジトリでZennのコンテンツを管理する方法 (初心者向けガイド)"
emoji: "🎉"
type: "idea" # tech: 技術記事 / idea: アイデア
topics: ["Zenn", "GitHub", "git", "QSG"]
published: true
---
一方、まだ、非公開(下書き)の場合は、false にします。
---
title: "GitHubリポジトリでZennのコンテンツを管理する方法 (初心者向けガイド)"
emoji: "🎉"
type: "idea" # tech: 技術記事 / idea: アイデア
topics: ["Zenn", "GitHub", "git", "QSG"]
published: false
---
ローカルリポジトリの全ての変更が「コミット」されれば(❶の表示)、リモートリポジトリへの「プッシュ」することが出来ます。リモートリポジトリとローカルリポジトリに差分がある場合で、ローカルリポジトリの内容が最新である時、❷「Publish branch」により、githubのリモートリポジトリへ「プッシュ」されます。


 7. Zennサービスへのコンテンツ公開上記、ステップ 6. まで完了すると、自動的に "Published" が true のコンテンツが公開になります。


 まとめ日々の技術のアウトプットは、将来的には何かの役に立つでしょう。折角なので、github に構成管理しておいて、いい感じでコンテンツがたまったら、ナレッジブックにでも拡張出来ればよいですね。
Zennのサービスから、直接ブログサービスのようにコンテンツを上げることが出来ますが、明らかにこちらの方法の方が自由度があります。特にコンテンツ管理においては、以下のオファリングが得られるのが強みですね。

簡単化 : Zenn CLIはGitHubと連携しており、記事や本の管理が容易。リポジトリにプッシュするだけで、Zenn上に自動的にデプロイ。

プレビュー : ローカル環境で記事の公開前のプレビューと変更が可能になる。

拡張性 : コンテンツを「本」としてナレッジブック化することができる(あわよくば、有償販売)

予約機能 : 記事の公開日時を指定することができ、計画的なコンテンツ公開が可能。

バージョン管理 : GitHubによるバージョン管理や、複数人によるコラボレーション執筆が可能。

カスタマイズ : 記事のタイトルやタグなど柔軟なコンテンツ管理が可能。
エンジニアのアウトプットには、モチベーションが期待できる場と思います。後は、バランスの良いシンプルな表示が、個人的にはgoodポイントになりました。