Creating rich link previews with Onebox

Documentation Using Discourse
,
1

:bookmark: This is a guide for creating rich link previews with Onebox in Discourse. It explains how to create Oneboxes, use inline Oneboxing, avoid Oneboxing, use hyperlinks, and handle advanced iFrames.

:person_raising_hand: Required user level: All users

Onebox converts your web links into useful preview excerpts that help inform readers about the target before they click through.

Summary

This guide covers how to:

  • Create Oneboxes
  • Use inline Oneboxing
  • Avoid Oneboxing
  • Use hyperlinks instead of Oneboxing
  • Handle advanced iFrames

Creating a Onebox

To create a Onebox, simply paste any link into a post on a line by itself, like so:

https://www.google.com/

This results in:

Onebox supports general oEmbed and OpenGraph tags, and has custom rules for popular sites like Wikipedia, Twitter, Amazon, YouTube, and others.

Try pasting links into your posts and see what happens. Just remember that for Oneboxing to work, the link must be on a line by itself!

Inline Oneboxing

With the enable inline onebox on all domains site setting enabled (this feature is enabled by default), 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/

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

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

Using hyperlinks

You can add a link to your text by:

  • Using the chain-link button in the editor toolbar
  • Selecting some text in your post and pasting a link from your clipboard
  • Adding 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. However, if the iframes are from highly trusted sources, a Discourse admin can whitelist that domain as an iframe target with the allowed iframes site settings.

You may also need to paste the full embed code, such as the one for the map below:

<iframe src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d24202.451099423397!2d-74.06201522657554!3d40.68924937923285!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x89c25090129c363d%3A0x40c6a5770d25022b!2sStatue+of+Liberty+National+Monument!5e0!3m2!1sen!2suk!4v1533203877892" width="600" height="450" frameborder="0" style="border:0" allowfullscreen></iframe>

This results in:

Additional resources

For further information and troubleshooting Oneboxes, please visit the related topic below:

Last edited by @hugh 2024-06-27T00:43:25Z

Check documentPerform check on document:
42 Likes