peps
peps copied to clipboard
python
Improve `meta name="description"` tag for rendered PEPs
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
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
Yeah, but that's already in the title element, which will be available and (if desired) displayed alongside the meta description so it doesn't really seem to make sense to repeat it again...
@hugovk ?
Bah, mis-click.
per "that describes the page" I'm somewhat inclined to include the title and PEP number too.
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.
I was going to suggest using https://pypi.org/project/sphinxext-opengraph/ like we've just started in CPython docs and the devguide:
- https://github.com/python/cpython/pull/99931
- https://github.com/python/devguide/pull/953
- https://github.com/python/devguide/pull/996
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:
<title>PEP 8 – Style Guide for Python Code | peps.python.org</title>
<meta name="description" content="Python Enhancement Proposals (PEPs)">
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.
If we're doing custom contents, I think the start of the first paragraph (e.g. Abstact, Introduction etc) would be good.
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.