Use sphinxext-opengraph to generate OpenGraph metadata #953

hugovk · 2022-10-06T00:27:22Z

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

ezio-melotti · 2022-10-06T01:24:34Z

conf.py

+
+# sphinxext-opengraph config
+ogp_site_url = "https://devguide.python.org/"
+ogp_image = "https://devguide.python.org/_static/python-logo.svg"


Apparently SVGs are not supported, so we should use a different image.

Should we also add more variables?

Will find another image. The recommended image size is 1200 x 630, should we use a Python logo or something else?

I don't think we need any of the other variables.

Re: other variables:

I'll check ogp_custom_meta_tags for <meta name="description">.

python/docs-community#65 (comment)

I'll check ogp_custom_meta_tags for <meta name="description">.

We can use ogp_custom_meta_tags to add it, but it would be hardcoded and we'd like to generate it from each page.

The recommended image size is 1200 x 630, should we use a Python logo or something else?

Since the image is rectangular (and somewhat big), it would be nice if it had both the Python logo and the text "Devguide". If/when we do the same for cpython (or for the peps repo), we can have the same logo but different texts, so that the links are easily distinguishable.

This however would require creating new images, so if you don't want to do that, just a simple logo will do (we can always update the image later).

I don't think we need any of the other variables.

ok

We can use ogp_custom_meta_tags to add it, but it would be hardcoded and we'd like to generate it from each page.

Right, it would be better if the description was created dynamically.

SVG replaced with a PNG of the Python logo + "Devguide".

I wrote a script to create it (hugovk/pixel-tools#15), so we can re-use that for other repos if we want.

I also squashed out the extra bytes from the PNG using optipng -o7 -zm1-9 _static/og-image.png (57,118 -> 9,573 bytes, 16.76% decrease).

When temporarily setting ogp_image = "https://cpython-devguide--953.org.readthedocs.build/_static/og-image.png" Facebook's sharing debugger shows the following OG metadata/preview:

https://developers.facebook.com/tools/debug/?q=https%3A%2F%2Fcpython-devguide--953.org.readthedocs.build%2F

Also included og:image:width and og:image:height because the debugger said "Using these tags will specify the image to the crawler so that it can render it immediately without having to asynchronously".

The new image looks good -- I wonder if we can use the same font used with the logo though.

https://www.python.org/community/logos/ says

The font used in the logo is called "Flux Regular". The PSF owns a copy but we cannot distribute it, except for work on the PSF's behalf.

Further down on the same page it says:

In general, we want the logo to be used as widely as possible to indicate use of Python or suitability for Python. However, please ask first when using a derived version of the logo or when in doubt.

So we should ask there first, and if they agree we can regenerate the logos with the right font.

This is not a blocker by any means though, so we can merge with the current image and recreate it later.

It's taking a while to get the font. It would be nice to get this merged to see how it works when live. Shall we merge this as-is, or with the image removed?

Let's merge it.
I'll ping Deb again about the font and we can update that in a follow-up PR.

(Continued in main thread: #953 (comment))

ezio-melotti · 2022-10-06T01:33:09Z

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).

…e an image

conf.py

ezio-melotti · 2022-10-10T22:39:35Z

conf.py

+
+# sphinxext-opengraph config
+ogp_site_url = "https://devguide.python.org/"
+ogp_image = "https://devguide.python.org/_static/python-logo.svg"


The new image looks good -- I wonder if we can use the same font used with the logo though.

https://www.python.org/community/logos/ says

The font used in the logo is called "Flux Regular". The PSF owns a copy but we cannot distribute it, except for work on the PSF's behalf.

Further down on the same page it says:

In general, we want the logo to be used as widely as possible to indicate use of Python or suitability for Python. However, please ask first when using a derived version of the logo or when in doubt.

So we should ask there first, and if they agree we can regenerate the logos with the right font.

This is not a blocker by any means though, so we can merge with the current image and recreate it later.

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

ezio-melotti

I tested the latest iteration and got this:

The website name works, but the image still doesn't (it loads for a while and then 💩).
This is because it currently points to https://devguide.python.org/_static/og-image.png, so the suggestion below should fix it.

conf.py

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

ezio-melotti · 2022-10-11T09:16:07Z

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. 🤔

hugovk · 2022-10-11T11:25:38Z

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

hugovk · 2022-10-30T13:54:02Z

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

…cription

hugovk · 2022-11-02T10:43:10Z

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 python/docs-community#65, my PR sphinx-doc/sphinxext-opengraph#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 (hugovk@483ee38)

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 · 2022-11-04T21:27:26Z

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 · 2022-11-04T21:45:57Z

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

hugovk · 2022-11-28T08:19:10Z

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

ezio-melotti · 2022-11-28T08:49:40Z

conf.py

+ogp_custom_meta_tags = [
+    '<meta property="og:image:width" content="1200">',
+    '<meta property="og:image:height" content="630">',
+    '<meta name="theme-color" content="#3776ab" />',


FWIW I looked into using a gradient that matches both colors of the Python logo, but this doesn't seem supported.

hugovk · 2022-11-30T13:52:37Z

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 · 2022-11-30T14:02:58Z

Facebook sharing preview

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

Before	After

Use sphinxext-opengraph to generate OpenGraph metadata

508bd4c

ezio-melotti reviewed Oct 6, 2022

View reviewed changes

ezio-melotti mentioned this pull request Oct 6, 2022

Add meta tags to docs.python.org python/docs-community#65

Closed

hugovk and others added 6 commits October 6, 2022 12:32

Merge branch 'main' into add-og-metadata

9f323a9

Merge branch 'main' into add-og-metadata

659a6c3

Merge branch 'main' into add-og-metadata

3a4f655

Merge branch 'main' into add-og-metadata

7e8173d

Create logo+text PNG for og:image, SVG not supported

b919f6c

Include og:image:width and height to ensure shares of new URLs includ…

d186e52

…e an image

hugovk force-pushed the add-og-metadata branch from 65f1738 to d186e52 Compare October 10, 2022 22:09

ezio-melotti reviewed Oct 10, 2022

View reviewed changes

Include og:site_name, displayed for the overall site

3b2e688

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

ezio-melotti reviewed Oct 11, 2022

View reviewed changes

conf.py Outdated Show resolved Hide resolved

Use relative path for ogp_image

5b048ea

Co-authored-by: Ezio Melotti <ezio.melotti@gmail.com>

hugovk mentioned this pull request Oct 30, 2022

Do not append index with dirhtml sphinx-doc/sphinxext-opengraph#77

Closed

hugovk added 2 commits November 2, 2022 12:14

Use sphinxext-opengraph 0.7.1+ to use meta og:description as meta des…

edd71a7

…cription

Merge branch 'main' into add-og-metadata

d3c69f7

Add theme colour using Python blue

684dff2

Regenerate OG image with Flux Regular

e47cc4f

ezio-melotti approved these changes Nov 28, 2022

View reviewed changes

hugovk merged commit 86770f2 into python:main Nov 30, 2022

hugovk deleted the add-og-metadata branch November 30, 2022 13:42

This was referenced Nov 30, 2022

Research ways to improve SEO python/docs-community#63

Open

Use sphinxext-opengraph to generate OpenGraph metadata python/cpython#99931

Merged

Replace og:image with 200x200 logo #996

Merged

hugovk mentioned this pull request Dec 8, 2022

Improve meta name="description" tag for rendered PEPs python/peps#2919

Closed

hugovk mentioned this pull request May 20, 2023

Added OpenGraph information to the documentation configuration urllib3/urllib3#3034

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use sphinxext-opengraph to generate OpenGraph metadata #953

Use sphinxext-opengraph to generate OpenGraph metadata #953

hugovk commented Oct 6, 2022

ezio-melotti Oct 6, 2022 •

edited

Loading

hugovk Oct 6, 2022

hugovk Oct 6, 2022

hugovk Oct 7, 2022

ezio-melotti Oct 7, 2022

hugovk Oct 10, 2022 •

edited

Loading

ezio-melotti Oct 10, 2022

hugovk Nov 27, 2022

ezio-melotti Nov 28, 2022

hugovk Nov 28, 2022

ezio-melotti commented Oct 6, 2022

ezio-melotti Oct 10, 2022

ezio-melotti left a comment •

edited

Loading

ezio-melotti commented Oct 11, 2022

hugovk commented Oct 11, 2022

hugovk commented Oct 30, 2022

hugovk commented Nov 2, 2022

TheTripleV commented Nov 4, 2022

hugovk commented Nov 4, 2022

hugovk commented Nov 28, 2022 •

edited

Loading

ezio-melotti Nov 28, 2022

hugovk commented Nov 30, 2022 •

edited

Loading

hugovk commented Nov 30, 2022

Use sphinxext-opengraph to generate OpenGraph metadata #953

Use sphinxext-opengraph to generate OpenGraph metadata #953

Conversation

hugovk commented Oct 6, 2022

ezio-melotti Oct 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hugovk Oct 10, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ezio-melotti commented Oct 6, 2022

Choose a reason for hiding this comment

ezio-melotti left a comment • edited Loading

Choose a reason for hiding this comment

ezio-melotti commented Oct 11, 2022

hugovk commented Oct 11, 2022

hugovk commented Oct 30, 2022

hugovk commented Nov 2, 2022

TheTripleV commented Nov 4, 2022

hugovk commented Nov 4, 2022

hugovk commented Nov 28, 2022 • edited Loading

Demo

Preview in Facebook

Preview in Slack

Choose a reason for hiding this comment

hugovk commented Nov 30, 2022 • edited Loading

Google's SEO checks

hugovk commented Nov 30, 2022

Facebook sharing preview

ezio-melotti Oct 6, 2022 •

edited

Loading

hugovk Oct 10, 2022 •

edited

Loading

ezio-melotti left a comment •

edited

Loading

hugovk commented Nov 28, 2022 •

edited

Loading

hugovk commented Nov 30, 2022 •

edited

Loading