It is widely known to regular users of DEV that DEV supports a variety of embeds using Liquid Tags, such as embedding GitHub repositories ({% github USER/REPOSITORY %}
), DEV user profiles ({% user USERNAME %}
), among others. Among the supported embeds are URL embeds, with DEV's editor guide providing a list of specifically supported URL embeds. A couple weeks ago I tried embedding a page from a site that is not in that list, specifically PyPI, and it worked.
If you want pages on your website to be embeddable in DEV posts, all that is necessary is the right combination of Open Graph meta tags in the head section of your page. So what Open Graph tags are required to get this to work here on DEV? My first attempt lead to DEV inserting an error message into my post rather than the page I was trying to embed, which lead to a question I posted last week. I couldn't find anything in DEV's documentation on this either. So after a bit of trial-and-error, here's how to get your webpages ready for embedding in DEV posts.
Disclaimer: Although this post concerns a DEV.to feature, I am not affiliated with DEV, and this is not official documentation.
Table of Contents: The rest of this post is organized as follows:
- Open Graph protocol
- Example embeds with and without required metadata
- How to enable DEV post embeds
- Where you can find me
Open Graph protocol
Facebook originally created the Open Graph protocol to enable treating any webpage as a rich object on Facebook. Many other social networking platforms have since adopted the Open Graph protocol for the same purpose, including right here on DEV.
To make your webpages shareable on sites that support the Open Graph protocol, you must include a few meta tags in the head section of your pages. This enables the site in question to build from your provided metadata a preview including an image from your site, rather than just a simple URL.
This post is not a complete tutorial on Open Graph. It also doesn't deal with which meta tags are required for the equivalent functionality to work on other social networking sites. This post is strictly about what is necessary to get your pages ready for embeds here on DEV.
Example embeds with and without required metadata
Let's first look at a few examples. First, DEV uses Liquid Tags in markdown to specify embeds. Here is the syntax:
{% embed https://url/to/the/page/to/embed %}
What DEV does with the above depends upon which, if any, Open Graph tags are present in the <head>
section of the page. Here's an example where the page in question doesn't have any Open Graph tags:
The above example is a page from the javadoc documentation for one of my projects. You'll notice that all that is presented is the URL to the root of the site where the page originates, which is actually a link to a more specific page somewhere on that site. This is a reasonable default for pages that lack Open Graph tags.
Here's another example from the same project, where I have inserted the Open Graph tags required by DEV into the head of the homepage for the project:
But be careful though. If you include only the tags listed as required in the Open Graph protocol, DEV will give you an error where a preview should ideally appear. I no longer have any such pages I can point to for a live example of this case, but here is what you will find in your post, instead of the embed, if you include only some, but not all, of the tags that DEV expects:
Liquid error: internal
So how do we fix the above error? And what specific Open Graph tags is DEV expecting? Read on to the next section for the details....
How to enable DEV post embeds
The Open Graph protocol lists four required tags: og:type
, og:title
, og:url
, and og:image
. It also indicates that depending on the value of og:type
that there may be additional required tags. For the type website
, which I'm focusing on in this post, those are the only tags listed as required by the Open Graph protocol. And in fact later the protocol indicates, "Any non-marked up webpage should be treated as og:type website," which I believe implies og:type
is only actually required if it is other than website
, such as music.song
, article
, profile
, or one of the other types in the protocol.
Minimal required metadata as specified by Open Graph protocol
If you only include the required metadata (from the protocol), you'll have something like the following somewhere inside <head></head>
, which will work for social shares on some sites, but is missing something that DEV expects.
<meta property="og:type" content="website">
<meta property="og:url" content="https://CANONICAL/URL/GOES/HERE/">
<meta property="og:title" content="TITLE GOES HERE">
<meta property="og:image" content="https://URL/TO/IMAGE/GOES/HERE">
And since I'm assuming the type is website, we can leave og:type
out and below should work equivalently to the above:
<meta property="og:url" content="https://CANONICAL/URL/GOES/HERE/">
<meta property="og:title" content="TITLE GOES HERE">
<meta property="og:image" content="https://URL/TO/IMAGE/GOES/HERE">
Minimal required metadata on DEV
Here on DEV, there is one more required Open Graph meta tag, specifically og:description
. The Open Graph protocol lists it among the Optional Metadata, and describes it as a "one to two sentence description". One simple approach would be to just copy the content of your description
tag.
Thus, to ensure that the pages on your website are embeddable within posts on DEV, include the following somewhere inside <head></head>
:
<meta property="og:url" content="https://CANONICAL/URL/GOES/HERE/">
<meta property="og:title" content="TITLE GOES HERE">
<meta property="og:image" content="https://URL/TO/IMAGE/GOES/HERE">
<meta property="og:description" content="DESCRIPTION GOES HERE">
Notice above that I don't have og:type
. Embeds work on DEV without it. Although if the type is anything other than website
, you may need it.
Among the very many optional tags in the protocol are tags for specifying the width and height of the image. I include them in my pages, but I am uncertain whether DEV uses them. If used, they should enable avoiding layout shifts during post load by reserving the required space while the image downloads. Here are the details if you want to include the width and height of the image.
<meta property="og:url" content="https://CANONICAL/URL/GOES/HERE/">
<meta property="og:title" content="TITLE GOES HERE">
<meta property="og:image" content="https://URL/TO/IMAGE/GOES/HERE">
<meta property="og:image:width" content="WIDTH_IN_PIXELS">
<meta property="og:image:height" content="HEIGHT_IN_PIXELS">
<meta property="og:description" content="DESCRIPTION GOES HERE">
There are more optional properties of images specified in the protocol.
Where you can find me
On the Web:
Follow me here on DEV:
Follow me on GitHub:
Vincent A Cicirello
View My Detailed GitHub Activity
If you want to generate the equivalent to the above for your own GitHub profile, check out the cicirello/user-statistician GitHub Action.
Top comments (3)
Thanks for investigating this. I have often wondered why my embeds using og: were not showing up correctly on some sites even though I had all the required items as well as
og:type
andog:description
.In your sample you have:
while my entries look like:
When I added the og properties, I apparently copied a meta tag like description which uses name/content not property/content.
I'm not going to ask why they decided to change the name from "
name
" to "property
" for these tags. Surprisingly somesites do accept name as well as property which confused
me even more when I saw them working.
Thanks again for writing this and making me take another look at it.
I'm glad you found it useful. I can't even begin to guess why Facebook went with "property" when "name" already existed. I'm guessing the sites where it works with "name" decided to support the likely errors.
Because "we're Facebook", NIH, not doing the research to realize
name
was already in use....