What makes a site compatible with onebox previews?

Support
1

I would like to help the developers of the following Python framework be compatible with onebox for our Discourse instance to promote it:

https://docs.sunpy.org/en/v3.0.0/whatsnew/3.0.html

So what makes a site compatible with onebox? I googled onebox and got to this github page: GitHub - discourse/onebox: (DEPRECATED) A gem for turning URLs into website previews · GitHub but for the framework I mentioned, they use Sphinx to auto-generate some of the pages so is there some settings the developpers can set with Sphinx to make their page compatible with onebox?

2

If you try to link https://docs.sunpy.org/en/v3.0.0/whatsnew/3.0.html in a line by itself you will see this message:

Sorry, we were unable to generate a preview for this web page, because the following oEmbed / OpenGraph tags could not be found: description, image

That page has an empty description OpenGraph meta tag, so we can’t embed it. It also uses relative URLs for some other OpenGraph tags, like image and url which I’m not sure it’s supported.

3

So I forwarded the info to the SunPy dev team. They tested a fix with this page: https://sunpy--5366.org.readthedocs.build/en/5366/, it was validated by opengraph.xyz, saying that all tags are defined in the html file:

<!-- HTML Meta Tags -->
<title>SunPy Documentation</title>
<meta name="description" content="SunPy Documentation">

<!-- Facebook Meta Tags -->
<meta property="og:description" content="SunPy Documentation">
<meta property="og:image" content="https://raw.githubusercontent.com/sunpy/sunpy-logo/master/generated/sunpy_logo_word.png" />
<meta property="og:site_name" content="SunPy Documentation" />
<meta property="og:title" content="SunPy Documentation">
<meta property="og:type" content="website">
<meta property="og:url" content="https://docs.sunpy.org/en/stable//index.html" />

<!-- Twitter Meta Tags -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:description" content="SunPy Documentation">
<meta name="twitter:image" content="https://raw.githubusercontent.com/sunpy/sunpy-logo/master/generated/sunpy_logo_word.png">
<meta name="twitter:title" content="SunPy Documentation">
<meta property="twitter:domain" content="https://docs.sunpy.org/en/stable/">
<meta property="twitter:url" content="https://docs.sunpy.org/en/stable//index.html">

Nonetheless, still doesn’t work in our Discourse instance, still getting the error: oEmbed / OpenGraph tags could not be found:description, image

Anything they are not seeing? Here’s our Github thread about this issue: onebox-compatible documentation for promoting SunPy's features and updates · Issue #5362 · sunpy/sunpy · GitHub

4

Is that an actual entry? The description should be longer, and contain a subset of the actual content on the page, not a placeholder like “SunPy Documentation”.

5

The description is being ignored because it’s identical to the title. You should be excerpting relevant parts of the content into the description property.