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?
- site address
- feature image
- product price
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
http://en.wikipedia.org/wiki/Ruby_on_Rails on a line by itself and you will see a nice onebox from Wikipedia
CLICK HERE FOR MORE EXAMPLES
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
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:
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 texttool 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:
#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:
#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
- Check that your site is using correct meta tags for content, ideally using the OpenGraph or oEmbed protocols
- Test your site by pasting the URL into iFramely to see how other sites see your content
- If that is working then make sure you’ve followed the correct process for posting the link in Discourse