CodePen supports oEmbed, a clever system for making it super easy to embed rich content. Here's an example of eEmbed: just drop a YouTube video URL on its own line in (say) a blog post, and it will get replaced with an actual embedded video.

That's just how CodePen oEmbed works, just drop a Pen URL into the content area of an oEmbed-enabled site and it will be converted into an Embedded Pen automatically.

Here it is working in WordPress:

That's a much more compelling experience than just a link, right! Of course you can use our Embed code also, which gives you more control, but it's cool how easy this can be. It also can bring embeds to places our Embed code might not work, like user comment areas.

Specifics about Using oEmbed in WordPress

WordPress (hosted .com and self-hosted .org) both support oEmbed. But they work off an internal "whitelist" of sites. Flickr and YouTube are among the list of about 20. We're going to work to get CodePen on that list, but for now it isn't.

It's easy to add support to your self-hosted site though. It's a one liner in your theme's functions.php file:

wp_oembed_add_provider('http://codepen.io/*/pen/*', 'http://codepen.io/api/oembed');

Or perhaps even better, there is a plugin to enable support. This is a good way to go, so that support persists no matter what theme you use.

That's it! Now it will work.

Minor notes about WordPress usage

If you're blogging in Markdown via the WP-Markdown plugin, oEmbed doesn't work, but Jetpack now enabled Markdown blogging and it does work through that.

oEmbed only works through post/page content in WordPress, but you can bring it to comments as well:

Comments on CSS-Tricks

How it Works

The oEmbed spec is pretty simple really. You create an endpoint on your site that accepts one URL parameter: another URL.

In our case, it's like this:

http://codepen.io/api/oembed?url=URL-TO-PEN-HERE

If that Pen is a valid Pen URL, it will return a JSON response, like:

{
  "success": true,
  "type": "rich",
  "version": "1.0",
  "provider_name": "CodePen",
  "provider_url": "http://codepen.io",
  "title": "CSS arrow down bouncing",
  "author_name": "Sherin",
  "author_url": "http://codepen.io/szs/",
  "height": "300",
  "width": "500",
  "thumbnail_width": "384",
  "thumbnail_height": "225",
  "thumbnail_url": "http://i.cdpn.io.s3.amazonaws.com/89176.JhgKC.small.0e6aa40d-a607-488e-9f7a-d1cfd94d2157.png",
  "html": "<iframe id=\"cp_embed_JhgKC\" src=\"http://codepen.io/szs/embed/JhgKC?height=300&slug-hash=JhgKC&default-tab=result&host=http%3A%2F%2Fcodepen.io\" scrolling=\"no\" frameborder=\"0\" height=\"300\" allowtransparency=\"true\" class=\"cp_embed_iframe\" style=\"width: 100%; overflow: hidden;\"></iframe>"
}

We return a "rich" content type, meaning supporting sites should use the HTML we return to display the content. That HTML, in our case, an <iframe> with the Embedded Pen.

This is a bit different than our regular Embed code, which usually features a semantic <p> tag and a <script>. What is cool about that is that the fallback content is still useful. Meaning if the site's content is read through RSS or JavaScript is disabled/broken or something, there is still meaningful content and links in there. When everything is working, that is flopped out with the embed <iframe>.

In the case of oEmbed, we return the <iframe> straight away, as:

  1. We aren't sure if it's even cool to return a script to execute with oEmbed, or if sites would execute it correctly (e.g. any escaping in that HTML would break it). Our goal is to get CodePen whitelisted as many places as we can and we've never seen any provider use script, so this is probably best.
  2. The fallback content is a link to the Pen anyway, which is decent.

Limitations

  1. For now we only allow /pen/ URL's. We might expand that. Opinions?
  2. You can't customize it. The embed will use the default theme and 300px height. To make this really easy we had to just make the call there. We might allow customization in the future for custom oEmbed setups. Let us know what you'd like to see.