Rich link previews with Onebox

Onebox converts your web links into useful preview excerpts that help inform readers about the target before they click through. To create a onebox, simply paste any link into a post on a line by itself, like so:

https://example.com/interesting-article

Once you’ve pasted the link, behind the scenes, onebox visits the destination page and checks for Open Graph or oEmbed tags, including:

  • site address
  • title
  • feature image
  • description (mandatory)
  • product price

:warning: Please note that Discourse does require the description tag to be present and contain enough text to summarize the page, or the target link will not onebox.

Which results in …

In addition to supporting general oEmbed and OpenGraph tags, Onebox has many custom rules for extremely popular sites including Wikipedia, Twitter, Amazon, Youtube, Soundcloud, Stack Overflow, Github and more.

Try it out! Play around with pasting links into your posts and see what happens. Experiment! Just remember, for oneboxing to work, the link must be on a line by itself! :man_scientist:

Inline Oneboxing

If you enable* the enable inline onebox on all domains site setting, pasting the link “inline” with the text, will replace the raw link with the title of the page, like this Understanding Discourse Trust Levels

like this https://blog.discourse.org/2018/06/understanding-discourse-trust-levels/

* this feature may be on by default in future Discourse releases

Avoiding Oneboxes

If you want the link to show up as a plain, unadorned raw link, place it in < brackets >

https://blog.discourse.org/2018/06/understanding-discourse-trust-levels/

<https://blog.discourse.org/2018/06/understanding-discourse-trust-levels/>

Alternately you can place a space before the link, or any characters after the link.

Using Hyperlinks instead

You can add a link to your text by using the chain-link button in the editor toolbar, or Markdown / BBCode / HTML links:

[link here](https://example.com)
[link=https://example.com]link here[/link]
<a href="https://example.com">link here</a>

Advanced iFrames

By default <iframe> is blocked for security reasons, but if they are from a highly trusted source, a Discourse admin can explicitly whitelist that domain as an <iframe> target in the site settings.

(you may need to paste the embed code such as the map above)

Troubleshooting

If Onebox is not working as expected, please check the following:

  • Test your site by pasting the link into iFramely; check that the target is using correct OpenGraph or oEmbed meta tags for content. And remember the description text is required in Discourse!
  • Verify that the onebox request to the target website has not been blocked by user-agent. Some WordPress hosts frequently block “unknown” user agents.

Admin configuration

Site administrators can control many of the onebox settings in the site setting section. To see available settings search for onebox. Notable settings are:

31 Likes