Add meta tags to docs.python.org
Mariatta opened this issue · comments
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
I think this is where we could get expert advice on what to write inside the title and description meta tags.
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:
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 tosphinxext-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).
The extension looks interesting. Looking at the comments, it seems like we can probably use the ogp_custom_meta_tags
?
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.
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).