はてなブログ記事のGitHub管理環境「push-to-hatenablog」のセットアップと使い方

しばらく、はてなブログから離れていましたが、絶賛、復帰検討中です！

復帰にあたり、GitHubではてなブログの記事を管理できないかと調べていた所、blogsyncというツールを使えばうまく行きそうだったので、試しに記事管理用の環境を作ってみました。

本記事では、作成した環境push-to-hatenablogのセットアップと使い方を解説したいと思います。

push-to-hatenablogの中身については、別記事で投稿予定です。

目次

簡単な流れ

まずは、push-to-hatenablogと、その中で使用しているblogsyncについて簡単に紹介したいと思います。

その後、push-to-hatenablogのセットアップ方法と使い方について解説していきたいと思います。

「blogsync」とは？

はてなの中の人が公開されている、はてなブログ用のCLIクライアントです。

はてなブログで提供されているAtomPub APIをラップして、はてなブログの記事を投稿、更新、取得をコマンドラインから行えるツールです。

詳細は以下のリポジトリを参照してください。

「push-to-hatenablog」について

今回紹介するpush-to-hatenablogでは、ローカル環境でDockerを使って、はてなブログ記事の取得と新規投稿を行います。

また、記事管理用のGitHubリポジトリを作成し、GitHubアクションを使って、編集・プッシュされた記事の更新を行います。

必要な環境

• Docker
• docker-compose

セットアップ

記事管理用のGitHubリポジトリを追加

それでは、早速、はてな記事の管理環境をセットアップしていきます。

まずは、記事管理用のGitHubリポジトリを追加してください。

push-to-hatenablog をクローン

以下のリポジトリをクローンして、リモートリポジトリを記事管理用に作成したリポジトリに変更するか、クローンしたファイルをローカルリポジトリに移動・設置してください。

blogsync.yamlの追加

blogsyncの設定ファイルblogsync.yamlを追加します。

ここで追加する設定ファイルは、ローカル環境から新規記事を投稿するときに使用します。

blogsync.example.yamlのファイル名をblogsync.yamlに変更してください。

blogsync.example.yamlの中身は以下の通りです。

[ブログのドメイン名]:
  username: [ユーザ名]
  password: [AtomPubのAPIキー]
default:
  local_root: entries

[ユーザ名]には、はてなアカウントのユーザ名を設定してください。

[AtomPubのAPIキー]には、はてなブログ管理ページの設定/詳細設定/AtomPubにあるAPIキーを設定してください。

blogsync.yamlのより詳しい内容は、以下のページを参照してください。

x-motemen/blogsync #Configuration

Secretの追加

記事の更新には、GitHubアクションを利用します。

ワークフロー中で必要になるSecretを設定していきます。

※ Secretsの設定は、追加したGitHubリポジトリページのSettings/Secretsから設定できます。詳細は以下のページを参考にしてください。

記事の更新時に以下の２つのSecretが必要となりますので、GitHubリポジトリに追加してください。

DOMAIN

DOMAINという名前のSecretを追加してください。値にはブログのドメイン名を設定してください。

BSY

BSYという名前で以下のような値のSecretを追加してください。

[ブログのドメイン名]:\n
  username: [ユーザ名]\n
  password: [AtomPubのAPIキー]\n
default:\n
  local_root: entries

ワークフロー中でblogsyncの設定ファイルを生成するために使用します。

ローカル用のblogsync.yamlとほぼ同じ内容ですが、各行の最後に改行コード\nを追加してあります。

ローカル用のblogsync.yamlと同様に、[ブログのドメイン]、[ユーザ名]、[AtomPubのAPIキー]を書き換えたものをSecretの値に設定してください。

「push-to-hatenablog」の使い方

記事の取得

既にはてなブログに投稿済みの記事をローカル環境にダウンロードするには、以下のコマンドを実行してください。

docker-compose run --rm blogsync pull ${domain}

${domain}にはブログのドメイン名を指定してください。

注意事項

記事取得はmasterブランチで行うようにしてください。

記事の取得前に使用中のブランチがmasterブランチであるか確認し、ブランチがmaster以外の場合はmasterブランチに切り替えてください。

はてなブログの更新はmasterブランチからの差分ファイルを対象としています。 masterブランチをプッシュした場合は、差分ファイルがないため更新処理が行われません。

逆に、masterブランチを利用する事で更新処理を回避することもできます。

記事数が多いと、はてなブログの更新に時間がかかります。 また、記事の取得処理で取得した記事については更新の必要がないので、記事の取得はmasterブランチで行い、記事の更新処理を回避するようにしてください。

特に初回の記事取得など、記事の取得数が多い場合はmasterブランチで取得するようにしてください。

新規記事の投稿

新規記事を投稿するには以下のコマンドを実行してください。 以下のコマンドにより、はてなブログとローカル環境に記事の下書きが追加されます。

docker-compose run --rm blogsync post --title=draft --draft --custom-path=${path} ${domain} < draft.md

${domain}にはブログのドメイン名を指定してください。

${path}には記事のパスを指定してください。
例: it/javascript/react-introduction

${path}に設定した記事のパスは、公開後の記事のパスに反映されます。
また、ローカル環境に追加される編集用ファイルのパスに対しても、${path}に設定した内容が反映されます。

記事の更新

編集した記事ファイルをGitHubへプッシュすると、GitHubアクションの更新ワークフローによって、はてなブログの記事が更新されます。

GitHubアクションのワークフロー設定の内容は以下を確認してください。

mm0202/push-to-hatenablog/.github/workflows/push.yml

注意事項

記事の編集前にブランチをmaster以外のブランチに切り替えてください。

その際、masterブランチからの差分ファイルが更新対象となりますので、記事の編集はmasterブランチ以外で行う必要があります。

まとめ

以上、push-to-hatenablogのセットアップと使い方について解説しました。

私自身も使い始めたばかりですが、そこそこいい感じに使えそうな気がします。
しばらく使ってみて投稿・更新フローが固まってきたら、使用例の紹介記事を書きたいと思います。

また、近いうちにpush-to-hatenablogの中身についての解説記事も投稿予定です。

動作不良や、問題点・疑問点など有りましたら、コメントより指摘していただけると助かります！