Rich link previews with Onebox

Onebox converts your web links into useful preview excerpts that help inform readers about the target before they click through. To create a onebox, simply paste any link into a post on a line by itself, like so:

Once you’ve pasted the link, behind the scenes, onebox visits the destination page and checks for Open Graph or oEmbed tags, including:

  • site address
  • title
  • feature image
  • description (mandatory)
  • product price

:warning: Please note that Discourse does require the description tag to be present and contain enough text to summarize the page, or the target link will not onebox.

Which results in …

In addition to supporting general oEmbed and OpenGraph tags, Onebox has many custom rules for extremely popular sites including Wikipedia, Twitter, Amazon, Youtube, Soundcloud, Stack Overflow, Github and more.

Try it out! Play around with pasting links into your posts and see what happens. Experiment! Just remember, for oneboxing to work, the link must be on a line by itself! :man_scientist:

Inline Oneboxing

If you enable* the enable inline onebox on all domains site setting, 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

* this feature may be on by default in future Discourse releases

Avoiding Oneboxes

If you want the link to show up as a plain, unadorned raw link, place it in < brackets >


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

Using Hyperlinks instead

You can add a link to your text by using the chain-link button in the editor toolbar, or Markdown / BBCode / HTML links:

[link here](
[link=]link here[/link]
<a href="">link here</a>

Advanced iFrames

By default <iframe> is blocked for security reasons, but if they are from a highly trusted source, a Discourse admin can explicitly whitelist that domain as an <iframe> target in the site settings.

(you may need to paste the embed code such as the map above)


If Onebox is not working as expected, please check the following:

  • Test your site by pasting the link into iFramely; check that the target is using correct OpenGraph or oEmbed meta tags for content. And remember the description text is required in Discourse!
  • Verify that the onebox request to the target website has not been blocked by user-agent. Some WordPress hosts frequently block “unknown” user agents.

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

1 Like

Try the post onebox maxlength setting.


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.

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


Hi there, I am having issue with Onebox conversion. When pasting Flickr Album link to a onebox in a post, we get the preview image only, without description, title nor clickable link. Henre, the link we want to share… is not even there (only if you show raw html from the post). I am not sure I can post onebox on this forum but I’ll copy the link here if by chance you can check what is wrong with it (!!

Yes you can see that it is not clickable


In the community I’m on, we often link to specific pages of However, since those pages require login and redirects to the login page if no one is logged in, the onebox actually shows the login page. I know you can circumvent this by putting a space, but many people don’t know this and don’t realize that the link they posted will just go to the login page.

I think any of the following would be improvements (ordered from most to least useful, in my opinion). Please let me know if any of these are possible and how they could be accomplished.

  1. Detect the user’s login cookies to (assuming they are logged in) so that onebox shows the proper preview. I recently suggested something similar and didn’t get any responses saying it was already supported, but if it is let me know. This does have the downside that users who are not logged in will still be confused.
  2. Always show a mini-onebox (if possible). The FAQ is a little sparse on how mini-onebox works, but it does mention that it grabs the title of the page. That means you’d once again have to be logged in in my case (to not be redirected), right? Is there any other way of specifying or detecting information to display a useful mini-onebox?
  3. Disable onebox entirely for the domain If there’s no way to get onebox or mini-onebox to work for this website, it would probably be best to just disable it outright. Is there a way to do that?

I appreciate any help and tips you can give!


Yes, add it to the domain blacklist for oneboxing.


Flickr onebox now indicates that the link is for an album, and clicking on that preview image redirects to Flickr album.


Is it possible to show movie ratings in IMDb oneboxes? If possible, maybe it could be right under the movie poster.


2 posts were split to a new topic: Xkcd onebox image getting resized