Use sphinxext-opengraph to generate OpenGraph metadata

[hugovk]

Add Open Graph metadata using https://github.com/wpilibsuite/sphinxext-opengraph.

[ezio-melotti]

The OGP tags are also used to generate previews (e.g. on social media). I did some testing using the preview build, and on Discord I got:

The preview (including title and text) show up, but there is no image -- apparently SVGs are not supported, so we need a different image. I got similar results elsewhere, except for Google Chat (it didn't generate any preview there, not sure why).

[ezio-melotti]

I saw that in the source of https://cpython-devguide--953.org.readthedocs.build/ there is a <meta property="og:url" content="https://devguide.python.org/index/" />, and https://devguide.python.org/index/ is a 404.

With the dirhtml builder sphinxext-opengraph is adding the name of the current page to the url: https://github.com/wpilibsuite/sphinxext-opengraph/blob/9f1a8c890ede83e11d24f20e569220873f5f71f8/sphinxext/opengraph/init.py#L89-L97

On the main page (i.e. /) this ends up appending an extra index/ resulting in the 404. We could add a redirect on our end, but I wonder if index should be special-cased upstream. :thinking:

[hugovk]

This would be better fixed upstream, as it will break for other sites using dirhtml. Please could you report?

[hugovk]

Reported at https://github.com/wpilibsuite/sphinxext-opengraph/issues/77 and created PR https://github.com/wpilibsuite/sphinxext-opengraph/pull/78.

[hugovk]

Reported at wpilibsuite/sphinxext-opengraph#77 and created PR wpilibsuite/sphinxext-opengraph#78.

The dirhtml bug is fixed and released in sphinxext-opengraph 0.7.1! 🚀

Also, to help https://github.com/python/docs-community/issues/65, my PR https://github.com/wpilibsuite/sphinxext-opengraph/pull/71 to use og:description as description is also part of 0.7.1 and enabled by default.

---

Here's a demo branch and build with the URL fixed so the image URL works (https://github.com/hugovk/devguide/commit/483ee38b0628c52ff981f60651f2709ea021aa74)

• https://hugovk-devguide.readthedocs.io/en/add-og-metadata2/

Here's a page in the Facebook sharing debugger:

• https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fhugovk-devguide.readthedocs.io%2Fen%2Fadd-og-metadata2%2Fversions%2F

Here's a Slack share (demo and current site):

And Discord:

[TheTripleV]

Noticed you have a Discord example. Adding a "theme-color" meta tag lets you customize the color of the vertical bar on the left side of the Discord embed. Example color config: https://github.com/wpilibsuite/frc-docs/blob/main/source/conf.py#L123 Example url with a color: https://docs.wpilib.org/en/stable/index.html

[hugovk]

Thanks for the tip! I updated this and the demo branch to use Python blue:

[hugovk]

I found the fonts in https://github.com/python/pythondotorg/tree/main/static/fonts so have regenerated the image using https://github.com/hugovk/pixel-tools/blob/1618b2a09bd5998899958856b7fef4503f95cba2/og_image.py like:

python og_image.py --logo tests/python-logo.png --size 210 --font ../pythondotorg/static/fonts/FluxRegular.ttf
...
optipng -o7 -zm1-9 _static/og-image.png # 16.28% decrease

Demo

https://hugovk-devguide.readthedocs.io/en/add-og-metadata2/testing/run-write-tests/

Preview in Facebook

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fhugovk-devguide.readthedocs.io%2Fen%2Fadd-og-metadata2%2Ftesting%2Frun-write-tests%2F

Preview in Slack

[hugovk]

Google's SEO checks

Using their PageSpeed Insights tool:

https://pagespeed.web.dev/report?url=https%3A%2F%2Fdevguide.python.org%2F&form_factor=desktop

Before: 91	After: 100

[hugovk]

Facebook sharing preview

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fdevguide.python.org%2F

Before	After