Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
pradyunsg opened this issue Dec 8, 2022 · 6 comments · Fixed by #3801
Closed

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

pradyunsg opened this issue Dec 8, 2022 · 6 comments · Fixed by #3801
Labels
enhancement infra Core infrastructure for building and rendering PEPs

Comments

@pradyunsg
Copy link
Member

pradyunsg commented Dec 8, 2022

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
@pradyunsg pradyunsg added the infra Core infrastructure for building and rendering PEPs label Dec 8, 2022
@AA-Turner
Copy link
Member

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
Copy link
Member

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 ?

@pradyunsg pradyunsg reopened this Dec 8, 2022
@pradyunsg
Copy link
Member Author

pradyunsg commented Dec 8, 2022

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.

@hugovk
Copy link
Member

hugovk commented 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.

image

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.

@CAM-Gerlach
Copy link
Member

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.

@hugovk
Copy link
Member

hugovk commented May 28, 2024

Please see PR #3801.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement infra Core infrastructure for building and rendering PEPs
Projects
None yet
Development

Successfully merging a pull request may close this issue.

5 participants
@hugovk @pradyunsg @AA-Turner @CAM-Gerlach and others