Consider adding OpenGraph meta data

[stevepiercy]

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

[ksuess]

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

• 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?
• 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.

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

[ksuess]

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]

• 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.
wpilibsuite/sphinxext-opengraph#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]

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]

What I mean with #529 (comment) 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]

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]

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