Skip to content
A gem for turning URLs into website previews
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib FIX: URL encode whitespace character globally Mar 16, 2019
spec FIX: Allow html tags in oembed html method Mar 6, 2019
templates FIX: respect code indentation Mar 7, 2019
.rspec change rspec command line options to format documentation Oct 3, 2013
.ruby-gemset we want to renamespace to Onebox Aug 7, 2013
.travis.yml Upgrade to Bundler 2 and fix Travis build Jan 7, 2019 bump version of onebox Feb 19, 2019
Gemfile Update reference to gemspec in Gemfile to drop discourse- Dec 17, 2013
Gemfile.lock Update Gemfile.lock Mar 8, 2019
LICENSE.txt Fix new engine instructions (#329) Feb 12, 2019
onebox.gemspec Upgrade to Bundler 2 and fix Travis build Jan 7, 2019


Gem Version Code Climate Build Status

Onebox is a library for turning media URLs into simple HTML previews of the resource.

Onebox currently has support for page, image, and video URLs for many popular sites.

It's great if you want users to input URLs and have your application convert them into rich previews for display. For example, a link to a YouTube video would be automatically converted into a video player.

It was originally created for Discourse but has since been extracted into this convenient gem for all to use!


Using onebox is fairly simple! First, make sure the library is required:

require "onebox"

Then pass a link to the library's interface:

require "onebox"

url = ""
preview = Onebox.preview(url)

This will contain a simple Onebox::Preview object that handles all the transformation. From here you either call Onebox::Preview#to_s or just pass the object to a string:

require "onebox"

url = ""
preview = Onebox.preview(url)
"#{preview}" == preview.to_s #=> true

Onebox has its own caching system but you can also provide (or turn off) your own system:

require "onebox"

url = ""
preview = Onebox.preview(url, cache: Rails.cache)
"#{preview}" == preview.to_s #=> true

In addition you can set your own options with this handy interface:

require "onebox"

Onebox.options = {
  cache: Rails.cache

url = ""
preview = Onebox.preview(url)
"#{preview}" == preview.to_s #=> true

Ruby Support

The onebox library is supported on all "officially" supported versions of Ruby.

This means you must be on Ruby 2.3 or above for it to work.

Development Preview Interface

The onebox gem comes with a development server for previewing the results of your changes. You can run it by running bundle exec rake server after checking out the project. You can then try out URLs.

The server doesn't reload code changes automatically (PRs accepted!) so make sure to hit CTRL-C and restart the server to try a code change out.

Adding Support for a new URL

  1. Check if the site supports oEmbed or Open Graph. If it does, you can probably get away with just whitelisting the URL in Onebox::Engine::WhitelistedGenericOnebox (see: Whitelisted Generic Onebox caveats). If the site does not support open standards, you can create a new engine.

  2. Create new onebox engine

    # in lib/onebox/engine/name_onebox.rb
    module Onebox
      module Engine
        class NameOnebox
          include LayoutSupport
          include HTML
          def data
              url: @url,
              name: raw.css("h1").inner_text,
              image: raw.css("#main-image").first["src"],
              description: raw.css("#postBodyPS").inner_text
  3. Create new onebox spec using FakeWeb

    # in spec/lib/onebox/engine/name_spec.rb
    require "spec_helper"
    describe Onebox::Engine::NameOnebox do
      let(:link) { "" }
      let(:html) { }
      before do
        fake(link, response("name"))
      it "has the video's title" do
        expect(html).to include("title")
      it "has the video's still shot" do
        expect(html).to include("photo.jpg")
      it "has the video's description" do
        expect(html).to include("description")
      it "has the URL to the resource" do
        expect(html).to include(link)
  4. Create new mustache template

    # in templates/name.mustache
    <div class="onebox">
      <a href="{{url}}">
        <h2 class="host"></h2>
        <img src="{{image}}" />
  5. Create new fixture from HTML response for your FakeWeb request(s)

    curl --output spec/fixtures/oneboxname.response -L -X GET
  6. Require in Engine module

    # in lib/onebox/engine.rb
    require_relative "engine/name_onebox"

Whitelisted Generic Onebox caveats

The Whitelisted Generic Onebox has some caveats for it's use, beyond simply whitelisting the domain.

  1. The domain must be whitelisted
  2. The URL you're oneboxing cannot be a root url (e.g. won't work, but will)
  3. If the oneboxed URL responds with oEmbed and has a rich type: the html content must contain an <iframe>. Responses without an iframe will not be oneboxed.


Add this line to your application's Gemfile:

gem "onebox"

And then execute:

$ bundle

Or install it yourself as:

$ gem install onebox

Issues / Discussion

Discussion of the Onebox gem, its development and features should be done on Discourse Meta.


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request
You can’t perform that action at this time.