Customize WordPress oEmbed for your Custom Post Types


Need to send invoices?
Check out my new WordPress plugin HDInvoice
Limited time launch sale

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

Native embed from looks great!

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

How my Documentation custom post type looked like by default

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 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") {
    $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") {
        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;

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

Liked this article? Sharing is caring

Leave a reply

πŸ‘ πŸ˜† 😠 😒 😍

Article Pulse

How people are reacting to this article.


This works great thanks!

I have a problem though. On my custom post type embed, the image and content is in two columns, but it looks bad, especially on mobile. Do you know how to fix?

reply 12 June 2023 - 02:18pm Fellow WP Developer 😍

Replying to: Fellow WP Developer

You can probably fix this with CSS. It’s hard to provide an exact example without being able to see it on your site, but you could probably just use CSS to add mobile specific styles.

I think that by default, WordPress sets images to float. So you could, for example, target your image to set it as a block element instead.

Something like:

@media (max-width: 800px) {
.wp-embed-featured-image img {display: block; float: none; width: 100%;}

reply 12 June 2023 - 03:25pm site admin Dylan πŸ‘