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.
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
Last checked by @hugh 2024-08-08T01:48:19Z
Check document
Perform check on document: