HugoテンプレートをOGPやTwitter Cardsに対応する

2021-01-11 Tool

2019年の5月よりHugoのThemeとしてInkblottyを公開していましたが、ついに初プルリクをいただきました。
そしてプルリクがOGPの機能追加に関するものだったのですが、知識不足やトラブルシューティングで調査・検証したので、備忘録を兼ねてメモしておきます。

OGP(Open Graph Protocol) / Twitter Cardsとは

Open Graph Protocolについて、公式サイトはこちら。
ざっくり日本語に訳すと「任意のWebページをソーシャルグラフ（≒ソーシャルネット？）上でリッチオブジェクトとして機能をもたせられるようにするもの」とのことですが…意訳すると「SNSやアプリにおいて高度な機能を提供するため、Webページを機械的に扱いやすくするためのオープンな規格」といったところでしょうか。
OGPでは以下のようにmetaタグを使い、“og:“から始まるpropertyとcontentを設定すればよいようです。

<meta property="og:title" content="Placeholder Text">
<meta property="og:description" content="Lorem Ipsum Dolor Si Amet">
<meta property="og:type" content="article">
<meta property="og:url" content="https://hugo-theme-inkblotty.netlify.com/placeholder-text/">

今までOPGという名称は知りませんでしたが、言われてみると最近いろいろなところで使われていそうな気がします。
LINE, Slack, ChatworkなどのアプリではWebページのリンクを貼り付けるとタイトル・要約・アイコンなどが表示されますが、ここにもOGPが使われているのかもしれません。

一方、TwitterではTwitter Cardsというものが使われているようです。Twitter Cardsの公式情報はこちら。
Twitter Cardsも同様にmetaタグを使うようで、“twitter:“から始まるnameとcontentを設定すればよいようです。

<meta name="twitter:card" content="summary">
<meta name="twitter:title" content="Placeholder Text">
<meta name="twitter:description" content="Lorem Ipsum Dolor Si Amet">

またTwitterにおいてもOGPは全く無関係というわけではなく、「Twitter Cards向けのプロパティが見つからない場合はOGPにフォールバックして動作する」という記載があります。

HugoのテンプレートにOGP / Twitter Cardsを導入する

OGP, Twitter Cardsのいずれも、HugoではInternal Templatesを使うことで簡単に導入できます。
~~それならなぜいままでやっていなかったのか。~~
具体的には以下の2行を<head>タグの中に追加するだけです。

{{ template "_internal/opengraph.html" . }}
{{ template "_internal/twitter_cards.html" . }}

使い方は公式ドキュメントにも記載されています。

Open Graph: https://gohugo.io/templates/internal/#open-graph
Twitter Cards: https://gohugo.io/templates/internal/#twitter-cards

検証方法

実装したつもりになるところまでは簡単なのですが、検証方法にちょっとだけ困りました。
が、どちらもツールが提供されていたので今後のためにメモしておきます。

Open Graph Protocolの検証用ツール

OGPの動作確認にはOGP確認を使わせていただきました。

ちなみにOGPがない場合であっても、どうやらLINEなどのアプリ自身も内容をある程度抽出してくれるようです。
なので検証できているのかいないのか分からなくなりがちですが、先ほど挙げたサイトはOGPの指定が足りなければメッセージを表示してくれるため、きちんと検証することができます。

Webにアップしていないと検証できないのが少しだけ厄介ですが、必要であればNetlifyで検証用のページを立てるなどすればOKでしょう。

Twitter Cardsの検証用ツール

Twitter Cardsについては、Twitterが公式の検証用のツールTwitter Cards Validatorを提供していることが分かりました。

最初は「検証するために自分のアカウントで呟くのも、テスト用アカウントを取得するのも、なんかやだな…」と思っていたのですが、そんな必要はありませんでした。
Twitterアカウントさえ持っていれば、ログインするだけで利用できます。

トラブルシューティング

検証中、exampleSiteでビルドするとエラーになることが分かりました。
エラー自体はOpen GraphのInternal Templatesの中で発生しているようで、具体的には以下のエラーです。

Error: Error building site: failed to render pages: render of "page" failed: execute of template failed: template: _default/single.html:3:7: executing "_default/single.html" at <partial "head.html" .>: error calling partial: execute of template failed: template: _internal/opengraph.html:41:17: executing "_internal/opengraph.html" at <index $siteSeries $name>: error calling index: index of untyped nil

実は今回、一番悩まされたのはこのエラーでしたが、結局以下のことが分かりました。

Hugo 0.59.1, 0.72.0, 0.80.0のいずれのバージョンでも再現する¹
テンプレートではなく、コンテンツに依存して発生する
exampleSiteのmarkdown-syntax.mdというコンテンツが含まれている場合のみ再現する

というわけで詳細を調べていったところ、コンテンツのFront Matterに以下の定義があるとエラーになることが分かりました。

series = ["Themes Guide"]

seriesについては、Hugo公式ドキュメントにはFront Matter Variablesにて以下の記載があります。

an array of series this page belongs to, as a subset of the series taxonomy; used by the opengraph internal template to populate og:see_also.

Open Graphに関する説明もあるのでやはりここが影響しているようですが、知識不足もあって詳細は分かりませんでした。
影響としてはog:see_alsoが適切に利用できなくなる程度だと思われるので、今回は原因究明を諦め、同梱のexampleSiteではこの行をコメントアウトするという回避策で済ませました。

所感

というわけで、HugoのテンプレートにおいてOGPとTwitter Cardsをサポートする方法についてでした。
知っていれば特に難しい話はなく、Google Analyticsなどと同様にInternal Templatesを導入するだけですね。
プルリクのおかげでOGPやTwitter Cardsについて理解を深めるきっかけになったので、その点はよかったです。

一方、HugoはまだまだWeb上に情報が少なく、トラブルシューティングになると大変なのを度々実感します。
以前にもuglyurlsというコンフィグを指定した場合の挙動についてIssueで質問を受けたのですが、このパラメータについてもなかなか情報が見つからず、解決にそこそこ時間がかかった記憶があります。

そんなわけでHugoの発展と、将来同じトラブルで困る人に貢献できれば…と思って書きました。
uglyurlsについても、時間があったら書いてみようと思います。

0.80を試してみたのは、2020年12月にOGPのInternal Templatesにも修正が入っていたためです ↩︎

Hugo

IT is my life