search

plone / training

Plone Trainings
https://training.plone.org
Creative Commons Attribution 4.0 International
58 stars 88 forks source link

Consider adding OpenGraph meta data #529

Closed stevepiercy closed 3 years ago

stevepiercy commented 3 years ago

See https://github.com/wpilibsuite/sphinxext-opengraph

ksuess commented 3 years ago

It' definitly worth adding OpenGraph meta data. Thanks for the hint! The sphinxext-opengraph extension does a great job for most chapters. Example http://localhost:3002/mastering-plone/dexterity_reference.html : text after heading is picked as og:description. That's fine and that's what I would expect. But

So from my point of view this extension is interesting, but does not fit enough to the needs of training.plone.org

ksuess commented 3 years ago

Two more thougts about OpenGraph meta data:

Apart from the fact that it would be handsome to write

---
html_meta:
  "description": "Theming with SemanticUI: Change font, favicon, …"
  "keywords": "Customizing, Theming, Volto, SemanticUI"
---

and get og:description from above html_meta description generated, the author can write

---
html_meta:
  "description": "Theming with SemanticUI: Change font, favicon, …"
  "property=og:description": "OpenGraph description"
  "keywords": "Customizing, Theming, Volto, SemanticUI"
---

The other point that i think is worth mentioning: does anybody want to twitter a training chapter? yes, they are hot stuff, but will they be twittered?

stevepiercy commented 3 years ago
  • I would expect that html_meta: "description" would be picked if it is present. It is unfortunatly not taken. Maybe I missed a configuration option?

This is by design. It does integrate with html_meta.

  • and chapters with a sidebar following the heading (mastering plone development) get og:description sidebar text. That's not OK. And we would have to modify the chapters text. That could be done, no too big effort.

See related issue. https://github.com/wpilibsuite/sphinxext-opengraph/issues/22

the author can write

---
html_meta:
  "description": "Theming with SemanticUI: Change font, favicon, …"
  "property=og:description": "OpenGraph description"
  "keywords": "Customizing, Theming, Volto, SemanticUI"
---

I had not thought of doing that. That's a great solution! Let's do this instead.

The other point that i think is worth mentioning: does anybody want to twitter a training chapter? yes, they are hot stuff, but will they be twittered?

Twitter, Facebook, and other social media that Plone Foundation uses. There is also an auto-post to Slack. I also just asked to auto-post to Discord. I think it would be useful. We've been looking for content to announce, and I can't think of anything more important to announce than Training documentation, except conferences.

stevepiercy commented 3 years ago

To summarize next steps, I would suggest that we start including the following OG meta information:

https://ogp.me/

"property=og:title": "OpenGraphPageTitle"
"property=og:type": "website"
"property=og:image": "OpenGraphPloneLogoURL"
"property=og:url": "OpenGraphPageURL"
"property=og:description": "OpenGraphDescription"
"property=og:locale": "en_US"
"property=og:site_name": "Plone Training"

I understand that that will lead to some duplication of meta tags, but I think it is worth it for better search results and social media posts.

ksuess commented 3 years ago

What I mean with https://github.com/plone/training/issues/529#issuecomment-923095978 is: It's an effort to get authors adding meta data to each chapter:

---
html_meta:
  "description": "description"
  "keywords": "keywords"
---

Now I wonder how to achieve, that every chapter even gets the additional "property=og:description": "OpenGraph description". Ideally this og:description would be generated by a plugin from --- html_meta: "description": "description" without the need that an author has to add it like:

---
html_meta:
  "description": "Theming with SemanticUI: Change font, favicon, …"
  "property=og:description": "OpenGraph description"
  "keywords": "Customizing, Theming, Volto, SemanticUI"
---
ksuess commented 3 years ago

I played a little bit with the extension sphinxext-opengraph. If 

---
html_meta:
  "description": "Theming with SemanticUI: Change font, favicon, …"
  "property=og:description": "OpenGraph description"
  "keywords": "Customizing, Theming, Volto, SemanticUI"
---

is added to a file, the explicit og:description is prioritized before the generated value from the plugin. That's good and allows to use the plugin.

So if a script adds a snippet

---
html_meta:
  "description": ""
  "property=og:description": ""
  "keywords": ""
---

to every file, the authors just have to fill in text.

A downside (but valuable) is, that the build throws warnings for every empty html_meta attribute.

See the branch https://github.com/plone/training/tree/sphinxext-opengraph with a script that adds the empty html_meta snippet.

So +1 from me for using the plugin together with added html_meta section for every file.

stevepiercy commented 3 years ago

Nice work!

I'd like to see a few more default meta tags. These are considered "basic" and should be included.

Per page:

"property=og:title": ""
"property=og:url": "https://training.plone.org/5/PATHTOMYPAGE"

In conf.py

ogp_image = "../_static/logo.png"  # does this actually resolve to a fully qualified URL?
ogp_type = "website"

I think your script could be incorporated into the Makefile, and then it could be run at any time from a universal location: make html_meta. Coincidentally I just saw an example of a Makefile that uses a Python-like scripting language:

https://github.com/pypa/warehouse/blob/main/Makefile#L14-L35

One final note, in requirements.txt, the correct package name is sphinxext-opengraph, whereas the extension name in conf.py correctly uses a . instead of a -.