search

wpilibsuite / sphinxext-opengraph

Sphinx extension to generate unique OpenGraph metadata
https://sphinxext-opengraph.readthedocs.io
Other
74 stars 27 forks source link

Is it possible to use the og:description for the regular meta description as well? #65

Closed msbt closed 1 year ago

msbt commented 2 years ago

Hi there! Grabbing the first piece of content and add it as og:description works fine, thanks a lot for that. I'm just curious if there is a way to also use this content as regular meta name="description" if nothing is specified otherwise via

.. meta::
   :description:

Would be very nice to have, any pointers on how to achieve that?

Daltz333 commented 2 years ago

I believe it was an intentional design decision to not modify any content besides OpenGraph. We found other extensions tended to also mess with meta information and it caused painful conflicts. Additionally, it could pretty quickly expand the scope of this extension to include other meta customization outside of OpenGraph.

You can however, inject global meta values using the ogp_custom_meta_tags field in your conf.py. If you want to expand this to an on per-page basis, you can look at the source code for this extension and modify it pretty easily to fit your use case.

msbt commented 2 years ago

Ah good point, that makes sense, thanks @Daltz333!

ItayZiv commented 2 years ago

I think it might be possible to consider a basic option to use the description we already generate as the default meta description, provided we don't deal with any special cases, overlaps or any other problems.

Reopening for now, I think it would be best if there was a setting in conf.py, disabled by default, and a per-page override to set the tag manually or remove the generated tag. (Using the meta directive would create 2 description tags, and taking care of that would require significant codes changes and/or additional dependencies)

msbt commented 2 years ago

Thanks for reopening @ItayZiv! May I ask if this is something you're planning to do in the foreseeable future?

hugovk commented 1 year ago

Please see PR https://github.com/wpilibsuite/sphinxext-opengraph/pull/71 to do the first part of this: add a Boolean setting to conf.py, that when enabled, will add the same description to <meta name="description" content="..."> as used for <meta property="og:description" content="...">.

msbt commented 1 year ago

This is great, thank you @hugovk!

Quick question though: Would this a) override a manual meta description or b) create a duplicate or c) won't be applied at all?

hugovk commented 1 year ago

@msbt Let's test it out! How do you set manual meta description?

hugovk commented 1 year ago

@msbt Let's test it out! How do you set manual meta description?

Like this:

.. meta::
   :description: My manual description

With that set, and enable_meta_description = True, we get b) duplicates: both the manual and automated.

I think it would be better to do c) only have the manual.

Also testing #71 on a bigger set of docs I see we're also getting multiple meta descriptions for subpages too. I'll take a look.

msbt commented 1 year ago

I think it would be better to do c) only have the manual.

Totally agree with you on that, appreciate your efforts!

hugovk commented 1 year ago

Please see https://github.com/wpilibsuite/sphinxext-opengraph/pull/72 to fix this!

TheTripleV commented 1 year ago

I'm open to adding support for meta descriptions to this extension, but want to make sure all of our bases are covered here. (#71 has been reverted while this decided).

Default Behavior

When the description is automatically parsed from the text, it would be written to both og:description and description.

Custom/Override Behavior

The custom version overwrites the auto-generated version. There's various ways to specify metadata. As above, 

.. meta::
   :description: My manual description

should work. Additionally, in Sphinx, just

:description: My manual description

should work as well. Sphinx automatically puts top level field lists in the context meta. As this extension already has some field list support, using

:og:description: My manual description

should continue to work as well.

I'm not sure on how to reconcile this on the following questions:

I'm inclined to keep them both separate but that would mean duplicated overrides in rst pages. Maybe specifying one overrides both, unless both are specified? Open to thoughts.

Note: The results of the aboves questions would apply in the future to overrides for :og:title: and :title: too.

hugovk commented 1 year ago

I'm not sure on how to reconcile this on the following questions:

  • If :og:description: is overridden, should the generated description change as well?

No, use overridden og:description for og:description, and generate description.

  • If :description: is overridden, should the generated og:description change as well?

No, use overridden description for description, and generate og:description.

  • What if both are overridden?

We:

I'm inclined to keep them both separate but that would mean duplicated overrides in rst pages. Maybe specifying one overrides both, unless both are specified? Open to thoughts.

I'm also inclined to keep them separate.

The reason is that whilst their contents will often be the same, it's possible they can be different as they're slightly different, semantically speaking.

One is the title of the webpage, for browsers, the other is the title of the thing to be shared, for Facebook and so on.

Someone may wish to tweak one or both.

So I suggest:

How's that sound?

TheTripleV commented 1 year ago

Sure, that sounds fine.

TheTripleV commented 1 year ago

Fun aside (source),

<meta name="description" property="og:description" content="great description">

is allowed and works to set both to the same value. I don't think it's applicable / nice to shoehorn this into rst field lists though.

hugovk commented 1 year ago

Fun aside 2:

Stack Overflow also combines some Twitter metadata with Open Graph metadata!

<meta property="og:type" content= "website" />
<meta property="og:url" content="https://stackoverflow.com/questions/6203984/combining-the-meta-description-and-open-graph-protocol-description-into-one-tag"/>
<meta property="og:site_name" content="Stack Overflow" />
<meta property="og:image" itemprop="image primaryImageOfPage" content="https://cdn.sstatic.net/Sites/stackoverflow/Img/apple-touch-icon@2.png?v=73d79a89bded" />
<meta name="twitter:card" content="summary"/>
<meta name="twitter:domain" content="stackoverflow.com"/>
<meta name="twitter:title" property="og:title" itemprop="name" content="Combining the meta description and Open Graph Protocol description into one tag" />
<meta name="twitter:description" property="og:description" itemprop="description" content="Is it possible to combine the meta description and Open Graph Protocol description&#x2026;&#xA;&#xA;&amp;lt;meta name=&quot;description&quot; content=&quot;My meta description copy.&quot; /&amp;gt;&#xA;&amp;lt;meta property=&quot;og:description&quot; content..." />