What is a “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?
Paste a URL into a post (on a new line with no blank spaces before) and that link is converted into a preview window.
Technical details
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:
What alternatives are there?
Onebox works automatically but you can alter the behaviour in certain ways
mini-onebox
If you do not want to show the full preview, then just paste the URL “inline” with the text, like this https://developer.nuki.io/guidelines/.
All URLs that are within Spoiler or Hide Detail tags will be mini-oneboxed only
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 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 our forum.
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.
https://developer.nuki.io/t/welcome-to-the-nuki-developer-forum/8/2
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 #discussion 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 #api