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

With the enable inline onebox on all domains site setting enabled*, pasting the link “inline” with the text, will replace the raw link with the title of the page, like this Understanding Discourse Trust Levels | Blog

like this

* this feature is enabled by default

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, by selecting some text in your post and pasting a link from your clipboard, or by adding 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.
  • If an internal link is not displayed as Onebox, make sure it is not in a secure category. For security reasons, internal links only Onebox in public categories or in the same category.

Admin configuration

Site administrators can control many of the onebox settings in the site setting section. To see available settings search for onebox. Notable settings are: