Customize WordPress oEmbed for your Custom Post Types

For the first time, I really needed and wanted to use oEmbed to have rich embeddable content to better cross-link between parts of my site. For example, I can use an oEmbed to embed the HD Quiz plugin page from WordPress.org

But what If I wanted to embed a documentation article (like this one) in a support thread, or cross-link documentation between articles? How can I change or modify the embed template?

The Problem

As you can see – it actually looks pretty great by default. But I see two problems with it.

The first issue is that the page title is just “HD Quiz”, which, although accurate (the page is literally called that), doesn’t signify that this is a documentation article.

The second issue is that if you look at the embed for the WordPress.org plugin page, the embed includes a “get this plugin” button link, but our Documentation custom post type only has the title as the link.

So let’s change that.

The Solution

Updating Titles

The first thing I want to do is update the title. Luckily, WordPress already has an easy-to-use filter the_title to change the titles of posts. But if I use this filter, it will update all the titles, which I don’t want to do. I only want to update the title inside embedded content, not actual page titles.

What’s cool is that WordPress has a function is_embed() to solve this for us. It works just like is_home(), is_search(), etc, and we can use it to check where we are.

Here is a full function example.

function hdplugins_update_embedded_title($title, $id)
{
    $post = get_post($id);
    if (is_embed() && $post->post_type === "documentation") {
        return "Documentation: " . $title;
    }
    return $title;
}
add_filter('the_title', "hdplugins_update_embedded_title", 10, 2);

Of course, change documentation to whatever the name of your custom post type is.

Adding a custom button to the embed

Now that we’ve prefixed all documentation titles with “Documentation” if embedded, let’s also add a button/link to it.

There’s actually two ways to do this. Depending on the content type, you can use either the embed_content action which allows you to add custom content after the rest of the content, or you can use the_excerpt_embed to edit the excerpt of the embed, assuming your embed contains an excerpt. For most cases, the_excerpt_embed is probably the better option, but I will use embed_content for this example since I don’t want to modify data, I just want to add something new.

function hdplugins_add_content_to_embeds()
{
    if (get_post_type() !== "documentation") {
        return;
    }
    $permalink = get_the_permalink();
    echo '<div class="wp-embed-meta"><a class="button" href="' . $permalink . '">Read Documentation</a></div>';
}
add_action('embed_content',  "hdplugins_add_content_to_embeds");

The above example takes whatever the HTML output of the embed was supposed to be, but also echos out a link wrapped in a div. As you can imagine, instead of getting the permalink, you could get some custom metadata or whatever else you want.

Adding custom CSS Styles (or JavaScript)

If you’re following along with this tutorial on your own site, you’re probably pretty happy with how easy it is to update the titles of your embeds, or add custom content to them. But that link is just a plain, boring, link. It doesn’t look like a button. So let’s add some custom CSS to make it look better.

function hdplugins_add_custom_styles_to_embeds()
{
    if (get_post_type() !== "documentation") {
        return;
    }
?>
    <style>
        a.button {
            background-color: #00749c;
            color: #fff;
            border: none;
            font-size: 1rem;
            border-radius: 3px;
            padding: 0.5em 1em;
            line-height: 1;
            display: inline-block;
            cursor: pointer;
            color: #fff;
            margin-top: 1em;
        }

        a.button:hover {
            color: #fff;
        }
    </style>

<?php
}
add_action('embed_head', "hdplugins_add_custom_styles_to_embeds");

And bam! Now the link looks much more like a styled native/integrated button. You can also add JavaScript this way too.

Here is what the final results looks like now