ZennとGitHub連携の手順メモ(普段Git使わない人用)

Zenn公式にはGitの詳細に関する記載がないので、それも含めてWindows環境でのZennとGitHubの連携手順メモ。普段GitHub使わない人(私)、WindowsでGit使わん人用。

Markdown記法のファイル(.md)を書いてGitHubに投げれば、自動でZennのサイトに掲載される仕組み。ここではテキストエディタにVisual Studio Codeを使い、そこからGitHubに投げるまでをまとめます。

メリット

• ブラウザのエディタから開放される。好きなエディタでサッと書ける
• GitHubに版管理を丸投げできる
• Zenn CLIを導入すればブラウザでの見た目をリアルタイムでプレビューできる(便利)

デメリット

• Zenn CLI、Git、VSCode諸々PC毎にセットアップ必要
• Zenn CLIにはNode.jsのインストール必要。Node.jsは頻繁にバージョン上がるので、人によっては環境競合するかも
• Gitにせよ何にせよWindowsで使うのはクソ面倒

手順は変わることもあります。基本は公式を参照ください。

Windows環境でLinux出自のgitコマンドとか使うと「\」と「/」がごっちゃになります。ついでに、PowerShellからコマンド入力する手順がありますが、PoweShellで「\」を入力すると\と表示されます・・注意が必要なところは補記しています。

手順

前提: Win11環境です。

(お約束)エクスプローラのオプションから「登録されている拡張子は表示しない」チェック外す、「隠しファイル、～を表示」チェック

Zennのアカウント作成

Zennのサイトでアカウント作成。

GitHubのアカウント作成

GitHubのサイトでアカウント作成。まずは無償版でOK。
※GitHubでは最近2段階認証が求められるようになってます、スマホにGoogle Authenticatorとかのアプリを入れておきましょう。スマホ用GitHubアプリでもOK。あとはGitHubサイトの指示通りにやればOKです。

GitHubでリポジトリ作成

GitHubのDashboardからTop repositories→Newでリポジトリ名を入力。
PublicでもPrivateでもOK。READMEファイル→不要、.gitignore→None、licence→NoneでOK。Create repository。

ZennとGitHubの連携

公式参照。

Visual Studio Codeをインストール

Gitのインストール前に入れておくのがおすすめ。公式からダウンロード。
起動したら左側の拡張機能からJapanese Language Pack for Visual Studio Code、GitHub Pull Requests、Markdown All in Oneあたりをダウンロードしておく。

Gitのインストール

Gitのサイトからダウンロード。
エディタはVisual Studio Codeを選択
Override the default branch name for new repositoriesが出たらmainを選んでおく

BLMとかの関係でmasterは良くないよねって流れ。もうマスタースレーブとか言っちゃいけないって最近知りました。

Use external OpenSSHを選択。Windows10からはOpenSSHが標準でバンドルされてるので、今回はそっちを利用。Gitとの連携手順は後ろの方を参照。他はそのままNextで大丈夫。

SSHはGitHubとの暗号通信に必須。ここではRSAの公開鍵方式を使います。
Gitに同梱されてるSSHを使わないのは、Windows界のSSHがカオスだから。

すごく分かりやすい・・です・・
なるべくWin謹製に寄せておくのが得策な気がする。

Gitへのパスが通ってるか確認
PowerShellから

> git --version

バージョン出たらOKなのでGitの設定に進む。
(以降の記載でも

> コマンド

という表記は、全てPowerShellからコマンドの部分を実行します)

もしgitコマンドが認識されなかったら

エラー出たらパス通ってない可能性が高い。Gitの場所を確認して環境変数PATHに追加

# エクスプローラかなんかでGitの場所を探してパスに追加。
# (場所はだいたいこのへん) *ここはバックスラッシュです*
> $env:PATH="$($env:PATH);C:\Program Files\Git\cmd"
# ただし、$env:PATHはセッション内限定なので消えてしまう。永続化する場合は
# ユーザ毎の設定:
> [System.Environment]::SetEnvironmentVariable("PATH", "$($env:PATH);C:\Program Files\Git\cmd", [System.EnvironmentVariableTarget]::User)
# PC全体の設定(管理者権限必要):
> [System.Environment]::SetEnvironmentVariable("PATH", "$($env:PATH);C:\Program Files\Git\cmd", [System.EnvironmentVariableTarget]::Machine)
# なんでパス通すのにこんなことなんねん...MSさん訳分からんで

または画面からPATH書き換える。(これ普段win使ってないとほんま場所よく忘れる)
Windowsキー+X→設定

→システム→バージョン情報

→「デバイスの仕様」の下にくっついてる「システムの詳細設定」

→詳細設定タブ→環境変数

→ユーザかシステムの環境変数からPathを選択して「編集」

→「新規」からGitのパス(C:\Program Files\Git\cmd)を追加

(どっちにしてもクソ面倒)

パスを通したらPowerShellを再立ち上げ。これで認識してくれるはず。

Gitの設定(最初だけ)

> git config --global user.name "ユーザ名"       #お決まり
> git config --global user.email "mail@address" #お決まり
> git config --global init.defaultBranch main #masterじゃなくてmainにしようね

configのリスト確認方法：

> git config list

↑でメールアドレスとか設定されてるのを確認
ちなみにWindows版でGit.configファイルの場所は以下の通り。(バージョンによって変わるかも)

C:\Program Files\Git\etc\gitconfig  # デフォルト
C:\Users\(ユーザ名)\.gitconfig       # ユーザ毎。メールアドレスとかはここに入るはず
(リポジトリフォルダ)\.git\config      # リポジトリ固有

GitHubにSSHキー登録

まず鍵作る。パスフレーズは省略できる(が非推奨)。鍵は接続先毎に変えておきたいのでファイル名を明示する。

# Windows環境でssh-keygenを使うときは、'~/'を解釈してくれないので代わりに$HOMEを使う
# $HOMEはC:\Users\(ユーザ名)に相当する
> ssh-keygen -t rsa -b 4096 -C "自分のmail@address" -f $HOME\.ssh\id_rsa_github
Enter passphrase (empty for no passphrase): #任意のパスフレーズを入力(覚えておく)
Enter same passphrase again: #もっかい入力

# もし作成済の鍵と名前が被ったら
Generating public/private rsa key pair.
C:\Users\(ユーザ名)\.ssh\id_rsa_github already exists.
Overwrite (y/n)?
# と聞かれる。 GitHubへの鍵登録が済んでいればこの手順はパス。

これで秘密鍵と公開鍵ができるので、公開鍵をGitHubに登録。公開鍵の場所は

C:\Users\(ユーザ名)\.ssh\id_rsa_github.pub

エクスプローラだとPC→Windows(C:)→ユーザー→(ユーザ名)→.sshで辿れる。

id_rsa_github.pubファイルを適当なテキストエディタで開いて(テキストエディタを入れてなければ「メモ帳」を開いてid_rsa_github.pubファイルをドラッグ&ドロップすればOK)、「中身のssh-rsa ～～～のテキスト」を丸ごとコピー。
GitHubのサイトから右上のアイコン→Settings→SSH and GPG keys→New SSH keyでKeyにコピーしたテキストをそのまま貼り付け→Add SSH key

OpenSSHエージェントサービスの有効化

WindowsのOpenSSHサービスは通常停止しているので、それを有効化する。前準備が必要。

1. .ssh\configファイルを作成
   C:\Users\(ユーザ名)\.sshフォルダ(さっきと同じ場所)にconfigという名前のファイルを作成する。(拡張子なし。テキストファイルを作成→拡張子を削除)
   適当なテキストエディタで開いて(拡張子削るとメモ帳では開けないのでファイルをドラッグ&ドロップ)、以下の内容をこのまんま貼り付ける。

   config

   Host github.com
     HostName github.com
     User git
     IdentityFile ~/.ssh/id_rsa_github
     AddKeysToAgent yes
   

   configの記述	意味
   Host	SSH接続時の名前(エイリアス)。github.comの代わりにghにすると、SSH接続をssh ghみたいに書ける
   HostName	リモートホストの指定。IPアドレスでもOK
   User	SSH接続のユーザ名。GitHubはgitユーザで接続する決まりなので、変えると接続できない
   IdentityFile	さっき作った鍵の片割れ(秘密鍵のほう)を指定。パスは\じゃなくて/なので注意。ちなみにWindows環境での~/はC:\Users\(ユーザ名)\を意味する
   AddKeysToAgent	yesを指定するとOpenSSHエージェント(この下の手順で起動するサービス)がSSHキーを覚えてくれる。パスフレーズも記憶してくれるが、パスフレーズはメモリ上に持つだけなので再起動後はまた聞かれる

2. OpenSSH Authentication Agentを起動
   Windowsのスタート→Windowsツール→サービスを開く
   OpenSSH Authentication Agentを探して、スタートアップの種類を自動にして適用
   さらに開始でサービスを立ち上げる。
   

3. SSHの起動・動作確認

   > Get-Service ssh-agent
   # サービスが起動しているとこんな感じになる
   Status   Name               DisplayName
   ------   ----               -----------
   Running  ssh-agent          OpenSSH Authentication Agent
   # SSHエージェントが機能していることのチェック
   > ssh -T [e-mail]
   The authenticity of host 'github.com (xx.xx.xx.xx)' cant be established.
   ED25519 key fingerprint is SHA256:～～.
   This key is not known by any other names.
   # 初めてつなぐ先だよ、という警告。yesと回答
   Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
   # 既知のホストとして登録されたよ
   Warning: Permanently added 'github.com' (ED25519) to the list of known hosts.
   # 最初はパスフレーズを聞かれるので入力
   Enter passphrase for key 'C:\Users\(ユーザ名)/.ssh/id_rsa_github':
   # これが出たらSSH接続成功
   Hi (ユーザ名)! You ve successfully authenticated, but GitHub does not provide shell access.
   > ssh -T [e-mail]
   # うまく設定できていれば、2回目はパスフレーズを聞かれない
   Hi (ユーザ名)! You ve successfully authenticated, but GitHub does not provide shell access.
   

4. GitがOpenSSHクライアントを使うように設定
   さっきインストールしたGitがOpenSSHを使えるように設定する。

   # 明示的にWIndowsのSSHサービスを使うように設定 *ここは\じゃなくて/なのに注意*
   > git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"
   

記事を管理するフォルダを作成

Zennの記事管理に使うフォルダを作成。このフォルダは同時にZenn CLIのためのNode.jsプロジェクトフォルダで、Gitのローカルリポジトリにもなる。(ここではD:\Zennとする。エクスプローラで作ってもOK)

> mkdir D:\Zenn
# ちなみにmkdirはPowerShellのコマンドレットNew-Itemのエイリアス。
# PowerShell的に書くと
> New-Item -Path "D:\Zenn" -ItemType Directory
# になるらしい。無理やり古のDOS窓、†cmd.exe†に似た動きにしてくれてるだけ。
# インターネッツ老人会のオッサンは非常に混乱する。

オーソドックスにドキュメントフォルダに作ってもOK。
その場合パスがC:\Users\私の 名前\Documents\Zennみたいになるが問題ない。

> cd ~\Documents\Zenn
# これで"C:\Users\私の 名前\Documents\Zenn"に移動できる。
# これを知るまでドキュメソトフォルダは絶対使わなかった。ちなみに
> cd ~/Documents/Zenn
# \じゃなくて/でも普通に動く。これもうわかんねぇな

Node.jsをインストール

公式サイト参照
セットアップ画面の中で、Automatically install the necessary tools. ～はチェックしなくてOK。

Zenn CLIをインストール

公式サイト参照。このとき、作成済のZenn用フォルダで実行する。

> cd D:\Zenn\
> npm init --yes # プロジェクトをデフォルト設定で初期化
> npm install zenn-cli # zenn-cliを導入
> npx zenn init

これでD:\Zenn\articlesフォルダが作成される。

もしnpmやnpxが認識されない場合は、Gitのときと同様にPATHを設定する。(だいたいC:\Program Files\nodejs\)

Gitのローカルリポジトリ作成

これも作成済のZenn用フォルダで実行。

> cd D:\Zenn
> git init

これでZennフォルダの中に隠しフォルダ.gitが作成され、ZennフォルダがGitのローカルリポジトリとして機能するようになる。以降は.gitフォルダの中身以外は全てGitの管理下になる。

Zennフォルダの中を見るとnode_modulesフォルダに大量のファイルが作られてるが、これらは.gitignoreファイルで無視されるよう設定されてるので、気にしなくて大丈夫。

リポジトリが機能しているかどうかは、git initを実行したフォルダで

> git status

で確認できる。リポジトリでなければ

fatal: not a git repository (or any of the parent directories): .git

のように怒られる。
ちなみに、隠しフォルダ.gitを削除すればGitのローカルリポジトリは完全に消滅する。

GitのローカルリポジトリとGitHubのリポジトリを紐付け

GitHubのサイトを開き、前に作成したリポジトリの画面に移動。
SSHのリモートアドレス([e-mail]:～～/～～.git)が表示されてるので、それをコピー。
(既に何かのファイルをpushした状態なら、Codeを開けば出てくる)

> git remote add origin [e-mail]:～～/～～.git
# originはGitHubのリポジトリ名に対する別名。originでなくてもいいがお決まり。

これでローカルリポジトリとGitHubが連携する。紐付けの状態は

> git remote -v
origin  [e-mail]:～～/～～.git (fetch)
origin  [e-mail]:～～/～～.git (push)

のように確認できる。

Markdown形式で記事の作成

公式参照。ただし、公式の

> npx zenn new:article

だとファイル名(slug)がランダムに生成されるため、

> npx zenn new:article --slug file-name-of-text

のようにslugだけは指定したほうがいい。(英数・ハイフン・アンスコ12〜50文字)

slugはユーザ内じゃなくてZenn全体でユニークである必要があります(知らんかった)。競合発生した場合の対処は後ろの方を参照。
soagsさんがslug衝突判定を作られてます。

Visual Studio Codeからファイル→フォルダーを開くでZennフォルダーを開いて、articleフォルダの下にできた.mdファイルを更新していく。
Markdown記法は公式参照。

プレビューの起動

公式参照。

# これもZennフォルダで
> npx zenn preview

ブラウザでhttp://localhost:8000を開くと、.mdファイルを更新する度にプレビューも更新されていく。便利。
これを実行しているPowreShellの窓を閉じると、プレビュー機能も停止するので注意。また、以降もgit関係の操作をPowerShellで行う場合、別のPowerShellウィンドウを開く。(同じようにZennフォルダにcdしておく)

Gitのステージング・コミット・プッシュ（記事の公開）

↓普段Git使わない人向け

Gitにはステージングという構造がある。

VSCodeで編集してる.mdファイルがいる場所はワーキングディレクトリ・作業ツリーと呼ばれ、そこからステージングエリアに移動(add)させてからローカルリポジトリにコミット(commit)する(必要なファイルだけコミットしたり、競合を解決する仕組み。ステージングはファイルや行単位、コミットはまとめて、のイメージ)。そこから更にpushしてGitHubに辿り着く。.mdファイルの編集くらいならファイル単位でボコボコaddしてcommitしてpushすればOK。

ファイルをステージングエリアに移動：

> cd D:\Zenn\                       #まずZennフォルダに移動
> git add .\articles\(ファイル名).md #特定のファイルをステージング
> git add .\articles\               #articles内の全ファイルをステージング
> git add .                         #Zennフォルダ下にある全ファイルをステージング

または、Visual Studio CodeでGitHub Pull Requestsを導入していれば(←なくてもOKだった)、ソース管理から変更したファイルの+マークでステージングできる。

ステージングが完了したら、ローカルリポジトリにコミットする。

> git commit -m "何を変更したかメモ"

またはVS Codeから

これでローカルリポジトリが更新されたが、まだGitHubには反映されていない。まず.mdファイルのpublished: falseで非公開状態にして試すのがオススメ。

# 最初は-uオプションでローカルリポジトリのmainとGitHubのリモートリポジトリを紐づける。
> git push -u origin main
# 一度-uオプション指定すれば、次からは
> git push
# だけでOK。

VS Codeの変更の同期でも同じ操作になる。

git push -uしてない状態でVS Codeから変更の同期しようとすると、以下のように聞かれる。今後は表示しないでOK。

これでZennのサイトに移動し、自分のアカウントから「記事の管理」で下書き状態が見れるようになったらOK。published: trueに変更してステージング→コミット→再プッシュして完了。

Zennのサイト上でも記事を更新できるが、Gitで再pushすると上書きされる

VS Codeでは、GitHubのリポジトリがローカルリポジトリを追いかけてる様子が見れる。

他にもGitHub DesktopなどGUIツールがいくつかあるので、好みのを使ってみてください。
個人で書く分には、Gitに関しては上図の一方通行で十分だと思います。(別のPCでも記事を更新するときは、pullや競合の解決とか必要になってくるので、詳細はそのうち別記事に書きます)

slugの競合が発生した場合

もしslugが他の人と重複した場合、GitHubにpushするとZennサイトにエラーが出る。

この場合、.mdファイルのslug(ファイル名)を変更し再push。
(ファイル名を変更するとGitはファイルの追加・削除と認識するので、追加と削除ファイルの両方をadd(ステージング)→commit→push)