はじめに #
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オプションによって、インストール元のチャンネルを指定します。
conda install -c anaconda sphinx
pipの場合は以下を実行します。
pip install sphinx
一方、sphinxext-opengraphはpipでのみインストール可能です。
pip install sphinxext-opengraph
プロジェクトテンプレートの作成 #
適当な空フォルダを作成し、sphinx-quickstartコマンドを実行してプロジェクトテンプレートを作成します。
sphinx-quickstart
詳細は以下の記事を参考にしてください。
Sphinxを使ったHTMLドキュメント作成 – Helve Tech Blog
設定ファイルの編集 #
Sphinxの設定ファイルconf.pyを開き、extensionsのリストに"sphinxext.opengraph"を追加します。
extensions = ["sphinxext.opengraph"]
OGPの設定 #
OGPの設定は、サイト全体と個別ページの両方に対して可能です。個別ページの設定が優先されます。
サイト全体 #
設定ファイルconf.pyに、サイト全体に対するOGPの設定を記載します。例を以下に示します。
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ファイルの例）。
<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ファイルの先頭に記述します。例を以下に示します。
: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が変更されている（上書きされた）ことが分かります。
<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を導入する方法をまとめました。
