Repository navigation
Improve meta name="description" tag for rendered PEPs #2919
Description
Currently, all PEPs get the description tag:
<meta name="description" content="Python Enhancement Proposals (PEPs)">
I noticed this due to the card that Discourse generated at https://discuss.python.org/t/21748. It would be an improvement to use a more informative description about the PEP other than the title in the description meta tag.
Why?
It conveys more context about the PEP in social cards and, well, on the preview card generated by Discourse.
What is worth including?
The most useful pieces of information would likely be the status of the PEP, the track and the topic associated with it.
The authors is probably also worthwhile addition since that's useful context to have as well (at least, more often than the delegate or post date in my experience) and makes each PEP's description relatively unique as well. And, author credits are a good thingTM IMO.
How should it be formatted/written?
Because this is slightly bikesheddy, I'll make a specific suggestion to base the discussion off of:
(PEP 691)
Accepted Standards Track Packaging PEP, authored by Donald Stufft, Pradyun Gedam, Cooper Lees, and Dustin Ingram
(PEP 801)
Active Informational PEP, authored by Barry Warsaw
Activity
AA-Turner commentedon Dec 8, 2022
From the specification: https://html.spec.whatwg.org/multipage/semantics.html#meta-description
It might be a little redundant but per "that describes the page" I'm somewhat inclined to include the title and PEP number too.
A
CAM-Gerlach commentedon Dec 8, 2022
Yeah, but that's already in the
titleelement, which will be available and (if desired) displayed alongside themeta descriptionso it doesn't really seem to make sense to repeat it again...@hugovk ?
pradyunsg commentedon Dec 8, 2022
Bah, mis-click.
I'm not aware of any situation where the description gets used/presented without the actual title.
From a quick Google search about this tag, it's basically all results are about SEO -- so https://developers.google.com/search/docs/appearance/snippet#meta-descriptions is possibly a useful document with examples.
hugovk commentedon Dec 8, 2022
I was going to suggest using https://pypi.org/project/sphinxext-opengraph/ like we've just started in CPython docs and the devguide:
It adds a bunch of Open Graph metadata, used in sharing previews, including a
<meta property="og:description" content="...">that it takes from the first X characters.Optionally, it can add
<meta name="description" content="..."using the same thing.But we might not want it filled up with the PEP headers' text?
Yep, I think we don't want to duplicate the
<title>info in<meta name="description">.Here's a quick demo with Discord.
Because there's no OG metadata, we can see how it's using the title and meta description:
So we wouldn't the contents to overlap.
If we're doing custom contents, I think the start of the first paragraph (e.g. Abstact, Introduction etc) would be good.
CAM-Gerlach commentedon Dec 8, 2022
For that, we would want to look for the Abstract header first, and only fall back to the first body paragraph if not found, since some PEPs have acceptance/rejection notices or other non-abstract/summary content as their nominal first paragraph.
hugovk commentedon May 28, 2024
Please see PR #3801.