Hugoの投稿をGitHubで管理するブログシステムのサンプル
概要
Hugo の Markdown 形式のブログ記事の投稿を、GitHub の Pull-Request の作法に則って検証するブログシステムのサンプルを作ったので、その解説をするという体で宣伝を目論む記事です。
主に含まれる成分は、以下です）
- チームでの運用を想定した運用フローと、それを記したドキュメント群
- CI で記事の形式的な検証をするためのスクリプト
なお、2 年ちょっと前に仕事で使うつもりで作ったけど結局使わなくなった仕組みであり、運用実績はありません。考慮漏れの事項がある可能性は高いです。
願わくば誰かに供養してもらえるとありがたいと思って記事にしました。
解説
基本的にはリポジトリを読んで理解してもらう前提で、ここでは特に取り上げたい点だけを列挙して解説します。
メンバーの役割は、投稿者・運営者・開発者
以下の役割が存在します。
- 投稿者
- ブログを投稿してくれる人々です。
- 主にはプログラマやデザイナなどの開発者を想定しています。
- 多数です。
- 運営者
- ブログの内容をレビューしたり、助言する人々です。また、本番へデプロイを行う人です。
- 主には職責としてブログを管理する人や、文章に強い人や、広範な知識を持つ開発者を想定しています。
- 数人です。
- 記事データの CODEOWNERS へ設定することで、自動で Reviewer として割り当てられます。
- 役割が重い気もするので、「ブログの管理をする人」「記事をレビューする人」に分けてもいいかもしれません。
- 開発者
- ブログを開発する人々です。
- ブログの投稿フローには無関係です。
README に、それぞれの役割用のドキュメントがあります。
記事検証用のスクリプト
記事検証用の Golang のスクリプトを CI で実行して、記事データが形式的に壊れていないことを検証できます。
おおよそ以下を検証しています。
- FrontMatter の値が規格通りか
- 記事に対する画像の配置場所が正しいか
また、Markdown 書式に対しての Linting をしたいときは、別の単体のツールを導入するのが良さそうです。
企画倒れになったプロジェクトでは、npm の markdownlint を使っていました。
記事を年毎にディレクトリ分けしている理由
「1ディレクトリに詰めても視認性が失われない」という以上に、特に理由はないです。
想定した運用ではその程度の記事数に収まる予定でした。
年/月 などの他のパスへ変えたいなら、Hugo の設定や各種スクリプトを調整する必要があり、いくつかのファイルを修正する必要があります。
常に Hugo 内部で UTC 扱いになる記事の時刻
Hugo の仕様ですが、記事の時刻が常に UTC であるとして内部で処理されます。
表示時に捻るなどをして、見た目上自然に動かすことは可能そうでした。
知る限りのことは、運営者のドキュメントへ書きました。
デザインのテーマ
現在は、何らかのテーマが必要だったので、Hugo Theme Gallerry から smol というテーマをお借りしています。
他のものもいくつか試したら、大体は動きました。
動かないものもありました。
企画倒れのプロジェクトでは、自前でデザイン・スタイルを開発していました。
なお、そのための Node.js ツールチェイン一式も入っていました。
GitHub 標準の Markdown エディタは使えないのか
可能ではあると思いますが、このサンプル記事の様に 画像がリンク落ちするのは困りそうです。
記事画像のパスを、Hugo と GitHub 両方で成立するように設定することができませんでした。
補足
GitHub で Markdown 記事を管理したいなら、Zenn で良くない？
そうですね...
おじゃんになった理由も、「どうせリプレイスするなら、マネージドなブログサービスにした方が良い」でした。
投稿フローのところだけは活かせそうだと思ってます。
Discussion