😸

GitHubリポジトリでZennのコンテンツを管理する

2020/09/06に公開
14

ZennにはWeb上のエディターが用意されていますが、GitHubリポジトリと連携すればローカルのテキストエディターで執筆することもできます。

GitHub連携時のイメージ

GitHubリポジトリと連携した場合、投稿コンテンツの作成や更新はすべてリポジトリ内で行います。登録したブランチに変更があると、zenn.devへ自動で同期(デプロイ)が行われます

同期するブランチの指定

GitHub連携が完了している場合、下記のページからブランチを変更できます。
デプロイ設定 →

コンテンツの作成

ローカルのテキストエディターなどでmarkdownファイルを作成し、編集します。ファイルの作成やプレビューにはZenn CLIを使用できます。

markdownファイルの編集後、リモートリポジトリ(GitHub)へプッシュします。登録したブランチへのプッシュやプルリクエストのマージによりデプロイが開始されます。

デプロイの進捗状況はヘッダーにアイコンで表示されます。

ダッシュボードのデプロイ履歴

デプロイ履歴はダッシュボードから確認できます。デプロイ時に発生したエラーもここでチェックします。

ダッシュボードのデプロイ履歴デプロイ履歴

内容の更新

内容を変更するときは.mdファイルを編集し、再度プッシュします。変更が加えられた.mdファイルのみがzenn.devに同期されます。

コンテンツの削除

安全のため、コンテンツの削除はダッシュボードの投稿管理からのみ行うことができます。

投稿管理ダッシュボード

GitHubとの連携手順

1. リポジトリを作成する

まずGitHubで好きな名前のリポジトリを作成します。公開設定はPublicでもPrivateでもOKです。この時点ではリポジトリの中身は空にしておきます。README.mdを作成する必要もありません。

GitHubでリポジトリを作成

2. Zennのダッシュボードから連携する

Zennにログインしたうえで、ダッシュボードのGitHubからのデプロイを開きます。

GitHub連携ページ

[リポジトリを連携]を選ぶと、リポジトリを選択する画面が表示されます。

GitHubでのリポジトリの選択

このとき必ず「Only select repositories」にチェックを入れて、連携するリポジトリだけを選ぶようにしてください。

これで連携は完了です。

3. 同期するブランチ名を確認

リポジトリ設定タブで同期したいブランチ名を確認・変更します。

リポジトリの設定

ここで登録されている名前のブランチに変更があったときに自動でデプロイが行われます。

ファイルの作成やプレビューはCLIで

ローカルでのファイルの作成や、markdownのプレビューにはZenn CLIを使います。具体的な使い方は下記のページをご覧ください。

📘 Zenn CLIの導入手順 →

GitHubリポジトリ連携についてのFAQ

連携するリポジトリを変更したい

ダッシュボードで連携を解除した後に、再度連携を行なってください。連携を解除しても同期されているデータはそのまま残ります。

連携するリポジトリを追加したい場合も一度連携を解除してから再連携を行っていただくようお願いします。

リポジトリにプッシュしてもデプロイされない

ダッシュボードからデプロイ履歴を確認してください。

プッシュされた内容に問題がある場合は、エラーメッセージが表示されます。

もしデプロイ履歴にログが出ていない場合は、GitHubのインストール済みのApplicationsの一覧からZenn ConnectのConfigureを開き、ダッシュボードに表示されている連携リポジトリとApplicationがアクセスを許可しているリポジトリが一致することを確認してください。

リポジトリ設定に表示されているリポジトリ

リポジトリの設定

▼ Applicationがアクセスを許可しているリポジトリ

Applicationがアクセスを許可しているリポジトリ

一致していない場合はデプロイされませんので、Application側のリポジトリを変更してください。また、連携するリポジトリを変更したい場合は、zennのダッシュボードから一度連携を解除してから再度連携を行ってください。

複数リポジトリ連携時に同じ記事を別リポジトリに移行することはできる?

slugが一致していればどちらのリポジトリから同期されても同じように上書きされます。そのため、記事や本のファイルを別のリポジトリに移動するだけで移行は完了します。

GitHubで編集を提案

Discussion

oliveroliver

オンラインエディタで公開した記事をGitHubのリポジトリに移行し、記事の内容を編集したいのですが、どのようにすればよろしいでしょうか?

手元ではリポジトリと既に連携済みで、オンラインエディタで作成した記事を編集しようとすると「GitHub連携しています。リポジトリで編集を行ってください」と出てしまいます。

Zenn公式Zenn公式

こちらさきほど修正を行い、GitHubリポジトリ連携していてもブラウザ上でエディターを開けるようにしました。
現状では本文をコピペしていただくことになります。お手数ですが、よろしくお願いします。

結城浩 / Hiroshi Yuki結城浩 / Hiroshi Yuki

どのようなMarkdownファイル名を付けたら第何章に対応するファイルになるのか、どのドキュメントを見ればわかるでしょうか。

Zenn公式Zenn公式

現時点ではチャプター番号.mdというファイル名にのみ対応しています。
3.mdは第3章に対応するというイメージです。

ドキュメント:CLIで本(book)を管理する

ただ、後から間にチャプターを差し込みたくなった場合にリンクの維持ができないので、今後このissueのようなアイデアで対応できないか検討しています。

ChiYoChiYo

オンラインエディタで公開した記事をGitHubのリポジトリに移動したいのですが、
touchコマンドでオンラインエディタに公開されているものと同じsligのmdファイルを作成し、
内容をコピペしてGitHubにpushする…とういう方法で合っているでしょうか?

Zenn公式Zenn公式

はい、2021年2月ではそのような形を取っていただく必要があります。まだしばらく時間はかかると思いますが、ZennからGitHubへのコミットもしくはプルリクエストの作成に対応したいと考えています。

さのたけとさのたけと

コンテンツをコピペして同名の slug を作って上書きする方法で,ウェブ上で作成していた本を GitHub に移したのですが,チャプターの数が多かったので大変でした.「設定内容を YAML で出力」という機能はありますが,コンテンツも含めてディレクトリを zip でダウンロードできる機能があると移行がしやすくなるかなと思いました(Zenn から GitHub へのプッシュがあれば理想的ですが,それができるまでの暫定対応として).

MzRyuKaMzRyuKa

GitHub連携をしようとすると、「必要なパラメータが存在しません」というエラーメッセージが出てきます。
Organizationsのprivateリポジトリを指定しているのですが、これが関係しているのでしょうか?

MzRyuKaMzRyuKa

いや、何かしらの権限が不足していただけっぽいですね。
取り急ぎ、リポジトリに対して「setting」ができる場合は、Organizations管轄のリポジトリでも問題なく連携できました。

MzRyuKaMzRyuKa

リポジトリに対して「setting」ができる場合は
正確ではなかった。結局のところ、Admin権限が必要だったというオチでした。

toshiki.chotoshiki.cho

連携済みのGitHubリポジトリに複数人が記事をpushした場合、コンテンツの作成者はどうなりますか?
コンテンツごとに作成者が反映されますか?

Zenn公式Zenn公式

その場合、コンテンツの作成者は、GitHubリポジトリを連携しているアカウント(ユーザー)になります。

toshiki.chotoshiki.cho

ご回答ありがとうございます。
この仕様はPublicationでも同様でしょうか?

Zenn公式Zenn公式

Publicationは、Publicationに所属するユーザーがPublicationに記事を投稿する形となります。
PublicationとGitHubリポジトリが連携しているわけではありません。

Publicationは無料でお使いいただけますので、ぜひさわってみてください。