Sphinxで生成するHTMLにSNSシェア用のOGPタグを設定する

※記事内に商品プロモーションを含むことがあります。

はじめに

Sphinxで生成する記事のHTMLに、SNSで詳細情報を伝えるためのOGP (Open Graph Protocol) を導入する方法をまとめました。sphinxext-opengraphという拡張機能を使用します。

リンク

環境

OSはWindows 10 Home Ver. 21H1です。

Python v3.9.7
Sphinx v4.2.0
sphinxext-opengraph v0.6.3

Sphinxとsphinxext-opengraphのインストール

Pythonは既にインストールされているものとして、Sphinxとsphinxext-opengraphをインストールします。

Sphinxはcondaとpipのどちらでもインストール可能です。conda環境では以下を実行します。-cオプションによって、インストール元のチャンネルを指定します。

1

conda install -c anaconda sphinx

pipの場合は以下を実行します。

1

pip install sphinx

一方、sphinxext-opengraphはpipでのみインストール可能です。

1

pip install sphinxext-opengraph

プロジェクトテンプレートの作成

適当な空フォルダを作成し、sphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。

1

sphinx-quickstart

詳細は以下の記事を参考にしてください。

Sphinxを使ったHTMLドキュメント作成 – Helve Tech Blog

設定ファイルの編集

Sphinxの設定ファイルconf.pyを開き、extensionsのリストに"sphinxext.opengraph"を追加します。

1

extensions = ["sphinxext.opengraph"]

OGPの設定

OGPの設定は、サイト全体と個別ページの両方に対して可能です。個別ページの設定が優先されます。

サイト全体

設定ファイルconf.pyに、サイト全体に対するOGPの設定を記載します。例を以下に示します。

1
2


ogp_site_url = "http://example.org/"
ogp_image = "http://example.org/image.png"

ogp_site_url: サイト全体のURLです。
ogp_image: OGPの画像です。画像ファイルを_staticフォルダに配置します。

以上のように設定して、通常のビルドと同じように.\make.bat htmlコマンドを実行します。すると、生成されたHTMLに以下のようなOGPタグが埋め込まれます（ReSTファイルindex.rstから生成されたHTMLファイルの例）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<meta property="og:title" content="Welcome to Test's documentation!" />
  
<meta property="og:type" content="website" />
  
<meta property="og:url" content="http://example.org/index.html" />
  
<meta property="og:description" content="Contents:: Welcome to Test's documentation!-.. Indices and tables: 索引, モジュール索引, 検索ページ." />
  
<meta property="og:image" content="http://example.org/image.png" />
  
<meta property="og:image:alt" content="Welcome to Test's documentation!" />

conf.pyのogp_site_urlに設定したURLが、5行目のmeta property="og:url"以降に出力されています。各ページの階層・HTMLファイル名が自動的に反映されます。

個別ページ

個別ページのOGP設定は、各ReSTファイルの先頭に記述します。例を以下に示します。

1
2
3
4
5
6
7


:og:description: Description of this page.
:og:image: http://example.org/image-of-this-page.png

Welcome to Test's documentation!
================================

...

:og:description:: ページの説明です。
:og:image:: OGPの画像です。画像ファイルを_staticフォルダに配置します。

以上のように設定して.\make.bat htmlコマンドを実行すると、以下のようなHTMLコードが生成されます。先程の結果と比較すると、og:descriptionとog:imageが変更されている（上書きされた）ことが分かります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<meta property="og:title" content="Welcome to Test's documentation!" />
  
<meta property="og:type" content="website" />
  
<meta property="og:url" content="http://example.org/index.html" />
  
<meta property="og:description" content="Description of this page." />
  
<meta property="og:image" content="http://example.org/image-of-this-page.png" />
  
<meta property="og:image:alt" content="Welcome to Test's documentation!" />

まとめ

Sphinxでsphinxext-opengraphという拡張機能を使用し、各記事にOGPを導入する方法をまとめました。

参考

GitHub - wpilibsuite_sphinxext-opengraph Sphinx extension to generate unique OpenGraph metadata