Customising your own WordPress oEmbeds

This makes perfect sense if you want to insert a “teaser” and encourage people to click through and read other related content on your site. The oEmbed technology was introduced to WordPress over a decade ago and has become ubiquitous; not least since the introduction of the Gutenberg editor and the provision of a large number of “embed blocks”.

As my own site runs on WordPress, that means I can embed previews of other blog posts and help visitors to find other content: not just by clicking on a boring link, but by showing them a preview of what they’ll get to see if they click through. For example, here’s a nice picture of Jo in Grindelwald many years ago.

Nice! Now you have a preview of the photo I’ve referenced, complete with the image title and a preview (or “excerpt”) of the text which goes with it. To embed this preview, all I did was search out the post I wanted, copied its URL, and pasted it into the edit screen of the blog post you’re reading now. That automatically used the oEmbed technology in the background to fetch the HTML – an iframe – which shows you the preview.

Customising the WordPress oEmbed appearance

WordPress’ oEmbed solution doesn’t appear to be particularly well-documented, as I had to search a bit and dig through the Core code to find what I was looking for. If you’ve come across embedded WordPress blog posts before, you’ll notice that the preview above looks different to how it usually appears. This is because I’ve used the following WordPress hooks to both enqueue an extra CSS stylesheet and modify the HTML output.

• embed_head
• embed_content
• embed_content_meta
• embed_thumbnail_image_shape
• embed_thumbnail_image_size

An alternative, if you really want to go nuts and change the HTML output completely, is to copy the file wp-includes/theme-compat/embed-content.php into your Theme and modify it directly. (Don’t change the original file, as your changes will be overwritten next time you update WordPress.)

I’ve restricted the changes to only apply when the HTTP referrer tells the page that the request is coming from the same site; embedding the same blog post or photo on a different site will still show the default embed view, shown below. (The embedded link immediately below this paragraph links to the WordPress.org information relating to embeds.)