Add meta tags to docs.python.org

[Mariatta]

We need to add <meta> tags to the output of sphinx documentation.

It looks like this is supported using the meta directive

https://docutils.sourceforge.io/docs/ref/rst/directives.html#meta

Example:

.. meta::
   :description: The reStructuredText plaintext markup language
   :keywords: plaintext, markup language

Some meta tags we should have:

• title
• description

Some advice according to: https://ahrefs.com/blog/seo-meta-tags/

Title meta:

• Write a unique title tag for each page;
• Be brief, but descriptive;
• Avoid generic and vague titles;
• Use sentence case or title case;
• Create something click-worthy—not clickbait;
• Match search intent;
• Include your target keyword where it makes sense;
• Keep it under 60 characters.

Description meta:

• Write a unique description for each page;
• Try to summarize content accurately;
• Avoid generic descriptions;
• Use sentence case;
• Create something click-worthy, not clickbait;
• Match search intent;
• Include your target keyword where it makes sense;
• Keep it under 160 characters

[Mariatta]

I think this is where we could get expert advice on what to write inside the title and description meta tags.

[ezio-melotti]

I don't think we should add them manually, but use an extension to automate the creation instead.

sphinxext-opengraph already does this for OGP meta tags (including automatically setting the title and description), but apparently not for regular meta tags. I haven't checked yet if there are other extensions that can add those, if not, we can create one similar to sphinxext-opengraph or make a PR against it to add this feature (if they are interested).

See also:

• Use sphinxext-opengraph to generate OpenGraph metadata devguide#953

[hugovk]

sphinxext-opengraph already does this for OGP meta tags (including automatically setting the title and description), but apparently not for regular meta tags. I haven't checked yet if there are other extensions that can add those, if not, we can create one similar to sphinxext-opengraph or make a PR against it to add this feature (if they are interested).

They're interested, there's a feature request to add <meta name="description">: wpilibsuite/sphinxext-opengraph#65).

[Mariatta]

The extension looks interesting. Looking at the comments, it seems like we can probably use the ogp_custom_meta_tags?

[hugovk]

We can't use ogp_custom_meta_tags because they would be hardcoded for all pages, and we'd like them generated for each page.

They're interested, there's a feature request to add <meta name="description">: wpilibsuite/sphinxext-opengraph#65).

I've created a PR for this: wpilibsuite/sphinxext-opengraph#71.

[hugovk]

Description meta tags have now been added by python/cpython#99931.

For example, https://docs.python.org/3/library/sys_path_init.html has:

<meta property="og:title" content="The initialization of the sys.path module search path" />
<meta property="og:type" content="website" />
<meta property="og:url" content="https://docs.python.org/3/library/sys_path_init.html" />
<meta property="og:site_name" content="Python documentation" />
<meta property="og:description" content="A module search path is initialized when Python starts. This module search path may be accessed at sys.path. The first entry in the module search path is the directory that contains the input scrip..." />
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
<meta property="og:image:alt" content="Python documentation" />
<meta name="description" content="A module search path is initialized when Python starts. This module search path may be accessed at sys.path. The first entry in the module search path is the directory that contains the input scrip..." />
<meta property="og:image:width" content="200" />
<meta property="og:image:height" content="200" />

See also #63 (comment).