Rich link previews with Onebox

(Robert McIntosh) #1

What do we mean by “Onebox”?

Onebox is an open source tool created by Discourse, and available to other sites, that converts your web links into useful preview windows that inform readers about the target before clicking.

How does it work?

For Discourse users, the process is seamless: Paste a URL into a post, and that link is converted into a preview window

  • start a post
  • grab the URL you want to link to
  • paste this on a new line with no spaces before
  • magic happens

… but technically?

Onebox visits the destination page and in most cases is able to determine a few key features of that page by checking Open Graph or oEmbed tags, or just general nifty algorithm stuff, including:

  • site address
  • title
  • feature image
  • description
  • product price

Like this:

If the link is to a retail site, it will also try to include the price:

In practice there are many different types of web sites, and Onebox has custom rules for many popular sites including twitter, amazon, youtube, soundcloud, stack overflow, github and more

One very cool feature Discourse has is “oneboxing”. If you include a link to your favourite site, it will try to create a usable snippet for you automatically.

For example: paste the link on a line by itself and you will see a nice onebox from Wikipedia


What alternatives are there?

Onebox works automatically but you can alter the behaviour in certain ways

If the user does not want to show the full preview, then pasting the URL “inline” with the text, like this Understanding Discourse Trust Levels, replaces the ugly code with the title of the page (if it exists).

All URLs that are within Spoiler or Hide Detail tags will be mini-oneboxed only

Some site owners with more complex needs (e.g. ticketing companies or Google Maps) can specify how their pages should load using iFrames. By default iFrames are blocked for security reasons, but if they are a trusted source, the Discourse admin can ‘whitelist’ them.

Note: you may need to paste the embed code such as the map above

If they are not whitelisted, Discourse will try to use Onebox rules instead.

add a hyperlink
Instead of inserting the URL you can add a link to your text by using the chain-link button in the menu bar, or by adding some brackets around your link and anchor text like this, following this pattern:
[anchor text](full_URL)

show the full text of the URL
If you really NEED to show the actual URL, then after pasting it into the edit window you can highlight it and use the </> Preformatted text tool in the menu bar, or simply add the ` (back quote) symbol either side of the URL

Internal Onebox links

Onebox works differently for links WITHIN a Discourse site.

links to individual posts (including the first post in a topic)

If you link to a specific post, the Onebox will display the avatar of the person who posted, the category and the first lines of the post. This appears in a styled indented ’box’ that also has an arrow in the top right of the box. Clicking this extends the preview box to show the full post.

This is to allow the reader to understand the full context of the post that has been shared without having to navigate away from the topic.

links to category or sub-category pages

Pasting the URL of a category page WILL NOT create a preview.

Category pages are navigation aids rather than content. It doesn’t add much to a discussion to SHOW a page that only lists other topics. If it will help a reader to see the category page on the same site, then they should visit that page.

The way to create a useful link to a category page within a conversation is to:

  • type # in the editor window (this cannot be the start of a new line but be inline as part of a sentence)
  • search for the tag by starting to type, or select from the suggested shortlist
  • select the relevant category (identified by the category title and colors)

e.g. Like this link to the #howto category

links to tags

Like categories, pasting the URL of a tag filter WILL NOT create a preview.

Selecting a tag to filter results is a navigation aids rather than content. The way to create a useful link to tagged posts within your conversation is to:

  • type # in the editor
  • search for the tag by typing
  • select the relevant tag (identified by the tag icon)

e.g. like this link to #user-interviews

troubleshooting / testing links

If Onebox is not working as expected, for example on your main site, aren’t working properly

  1. Check that your site is using correct meta tags for content, ideally using the OpenGraph or oEmbed protocols
  2. Test your site by pasting the URL into iFramely to see how other sites see your content
  3. If that is working then make sure you’ve followed the correct process for posting the link in Discourse

Discourse New User Guide
Onebox in details tag
Onebox challenges
Discourse New User Guide
What is a onebox?
(Sam Saffron) #2


Do we need 2 faqs here?

(Joshua Rosenfeld) #3

These should be combined. @techapj’s topic has far more examples, but little other explanation/details. @robmc’s has the explanations. Also, the older topic does not detail internal or mini oneboxes.

(Robert McIntosh) #4

Yes, there was a need for detailed explanation as this gets asked about a lot. I link to the examples in the earlier post but they also take a lot of space so have not merged them - but I can if we think it will help.

(Joshua Rosenfeld) #5

It’d be great if we could hide them in [details], but that breaks them.

(Julian Elve) #9

Liking this batch of user documentation posts @robmc - really timely for us setting up a new site!

(Jordan) #10

@robmc How did you create that accordion menu entitled “CLICK HERE FOR MORE EXAMPLES”? I’d like to leverage that in our community!

(Robert McIntosh) #11

In the editor panel, click on the gear icon in the formatting menu bar. This function is called…

Hide Details

This text will be hidden

(Jordan) #12

Thank you! I’m glad to know this!

More Details
  • I know this is out of the context regarding Onebox previews
  • Feel free to delete my comments if you feel it’s cluttering the topic thread.

(V Williams) #13

Is there a way to edit how much text is shown in each Onebox preview?


Try the post onebox maxlength setting.

(V Williams) #16

Actually that setting is in “OneBox” under admin settings :sweat_smile:

My real question is, is there a way to edit the feature image for the home page’s onebox? Right now it’s currently the Discourse logo.

(Robert McIntosh) #17

Yes, there is, though that is not a Onebox setting.

You are talking about the default opengraph image url since it is the Open Graph image that you select which will determine what appears in the Onebox preview. You will find this by searching in your Admin Settings, or under ‘Required’ settings

(V Williams) #18

Awesome, thank you both!

(V Williams) #19

Hey all, back again. I inserted an image url in the default opengraph image url section under “Required.” For some reason it isn’t working in Slack or Facebook. But when to check it on iFrame it showed the logo. Any ideas on why that might be?

(Robert McIntosh) #20

If iframely is showing it, it might be something specific to those tools rather than your site - most likely a cache issue?

Have you tried visiting Debugger - Facebook for Developers ?

(V Williams) #21

Hey all, back again. Is there a way to set all open graph images in Onebox to the default image I set, regardless of if the link is to a reply. For example:

Our logo shows in Onebox when linking to the topic itself.
The repliers logo shows in Onebox when linking to their comment. <-- Can I change this so it’s always our logo?