How to Enable DEV Post Embeds for Pages From Your Website
Tags: meta, webdev, tutorial, html
Published: 2022-07-29 15:08:39

It is widely known to regular users of DEV that DEV supports a variety of embeds using [Liquid Tags](https://dev.to/p/editor_guide#liquidtags), 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](https://dev.to/p/editor_guide) providing a list of specifically [supported URL embeds](https://dev.to/p/editor_guide#supported-url-embeds-list). 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](https://dev.to/cicirello/for-embeds-does-dev-use-open-graph-tags-and-what-is-the-minimum-set-of-og-tags-required-by-dev-for-an-embed-to-work-3kh3). 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](#open-graph-protocol)
* [Example embeds with and without required metadata](#example-embeds-with-and-without-required-metadata)
* [How to enable DEV post embeds](#how-to-enable-dev-post-embeds)
  * [Minimal required metadata as specified by Open Graph protocol](#minimal-required-metadata-as-specified-by-open-graph-protocol)
  * [Minimal required metadata on DEV](#minimal-required-metadata-on-dev)
* [Where you can find me](#where-you-can-find-me)

## Open Graph protocol

Facebook originally created the [Open Graph protocol](https://ogp.me/) 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](https://dev.to/p/editor_guide#liquidtags) in markdown to specify embeds. Here is the syntax:

```markdown
{% 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:

{% embed https://chips-n-salsa.cicirello.org/api/org.cicirello.chips_n_salsa/module-summary.html %}

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:

{% embed https://chips-n-salsa.cicirello.org/ %}

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](https://ogp.me/) 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.

```html
<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:

```html
<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](https://ogp.me/#optional), 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>`:

```html
<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.

```html
<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](https://ogp.me/#structured) specified in the protocol.

## Where you can find me

On the Web:

{% embed https://www.cicirello.org/ %}

Follow me here on DEV:

{% user cicirello %}

Follow me on GitHub:

{% github cicirello/cicirello %}

|  |  |  |
| :---: | :---: | :---: |
| [![Liberapay](https://actions.cicirello.org/images/Liberapay.svg)](https://liberapay.com/cicirello) | [![Ko-Fi](https://actions.cicirello.org/images/ko-fi.svg)](https://ko-fi.com/cicirello) | [![GitHub Sponsors](https://actions.cicirello.org/images/github-sponsors.svg)](https://github.com/sponsors/cicirello) |