OG Image Generator

Paste a web address into a message and, a moment later, it grows a picture, a headline and a line of gray text. Nobody at the receiving end designed that card. The software fetched the page, read a few tags near the top of it, and assembled the result from whatever it found.

The author of the page controls only the ingredients. How large the picture is drawn, whether it is cut to a square, and how much of the headline survives are decided elsewhere, by programs the author will never meet. That is the whole difficulty of the craft, and it is why a preview picture deserves more care than its small size suggests.

Where the four tags came from

The vocabulary most of these programs read is the Open Graph protocol. Its own page says it was originally created at Facebook and was inspired by Dublin Core, link-rel canonical, Microformats and RDFa. It was first published in 2010. The stated aim was modest and practical: give developers one thing to implement so that any web page could be described as an object with a title, a type, a picture and an address.

The specification is short enough to read in one sitting, and it is published under the Open Web Foundation Agreement, which grants a royalty-free copyright licence to reproduce and implement it. The same handful of tags is now read by software its authors may never have had in mind, messaging apps among them.

The protocol asks every page for 4 properties: a title, a type, a picture and the canonical address of the page. Everything else is optional, though a description and a site name are recommended. Each is written as a meta tag in the head of the document, with the name of the property in one attribute and its value in another.

There is an oddity worth knowing. The HTML Standard defines the meta element and its name and content attributes, but the property attribute that Open Graph tags use is not defined there. Google’s teaching material on metadata says so plainly: the attribute is not in the official specifications, yet it is widely supported by the applications that read the protocol. The convention works because readers agreed on it, not because a standard requires it.

How a link becomes a card

The same teaching material describes what happens when the tags are missing: the reading software falls back to the page title and the ordinary description tag. A card still appears, but it has no picture, or a picture chosen by guesswork. Supplying the tags is how an author takes the decision back.

The picture tag has helpers. The protocol lets a page state the picture’s media type, its width and its height in pixels, and a text alternative. They are written directly after the picture tag they describe, because the protocol treats them as properties of that picture. Stating the dimensions means the reader does not need to download the file to learn its shape, and leaving them out is an easy omission.

The address of the picture should be absolute. A generic address begins with a scheme, and a program that reads the tag from a copy of the page has nothing to resolve a relative path against. Write the full address, beginning with https, and the question never arises.

The values need care too. An attribute written between double quotes must not contain a literal double quote, and an ampersand that could be mistaken for the start of a character reference is an error. A headline such as Tom & Jerry say “hi” has to be written with its ampersand and its quotes as character references, or the tag ends early and the rest of the headline spills into the document as stray attributes. Accented letters, by contrast, need no treatment at all in a UTF-8 page.

One picture, several crops

Here the open specification falls silent. It says a page has a picture; it says nothing about how large that picture should be or what shape it will be shown in. Each program decides for itself. A wide picture may be shown whole in one place, cut to a square thumbnail in another, and clipped to a circle in a third.

This essay quotes no service’s figures, because none could be found in a source that may be relied on here. What can be said honestly is that 1200 by 630 pixels is a size designers commonly choose, a convention and not a rule, and that a careful designer plans for the crops instead of trusting any single one.

The planning is geometry. Take the tool on this page and its first example, a 1200 by 630 picture. Its own rule keeps words away from the edges by 6 percent of the shorter side: 6 percent of 630 is 37.8, so the margin is 38 px. A centered square crop keeps a region 630 pixels wide, beginning 285 pixels from the left edge, and a round crop keeps the circle inside that square. Words placed within the circle survive all three treatments.

The cost is visible at once. A title confined to the middle 630 pixels must wrap sooner, and a layout with the picture beside the title cannot be made square-safe at all. That is a real trade, and the right answer depends on where the link will mostly travel. The tool marks which pieces of text each crop would cut; it does not pretend the trade away.

Legibility when the card is small

A preview picture is an image of text, and the W3C accessibility guidelines treat images of text like text. They ask for a contrast ratio of at least 4.5:1 between letters and what lies behind them, relaxed to 3:1 for large text, which the guidance describes as about 18 point, or 14 point bold. The ratio comes from the relative luminance of the two colors and runs from 1 to 21.

The formula is easy to check by hand in the tool. Set the example’s background to the flat color #17324d with white text and the reading is 13.1:1. Set white behind gray text of #777777 and it drops to 4.48:1, just short of the floor; one step darker, #767676, passes at 4.54:1. Over a photograph there is no single background color, so the tool reads every pixel behind each line and reports the worst.

The guidance also warns that thin strokes are rendered fainter than their nominal color by anti-aliasing. That matters more when a 1200 pixel picture is drawn 320 pixels wide. The tool’s own rule of thumb, which is its guidance and nobody’s standard, asks that a title still be 12 pixels tall at that width. On a 1200 pixel picture that works out to 45 px.

Fitting text into a box is harder than it looks. Unicode defines the grapheme cluster as the user-perceived character, and a family emoji or a letter with stacked accents is one cluster made of several code points. Cutting a headline between code points can leave half a character behind, so truncation has to happen at cluster boundaries. Even then, the order of right-to-left and left-to-right runs follows the Unicode Bidirectional Algorithm inside the browser, and an ellipsis added in typing order may not land where a reader of that script expects.

Measurement has a trap of its own. The advance width of a line can be smaller than the ink it paints, because slanted or overhanging glyphs reach past their boxes. A layout that trusts the advance width alone will, now and then, let a letter cross the edge of its box.

The parts people forget

Alt text is the first. The protocol says the text alternative describes what is in the image and is not a caption, and that a page which gives a picture should give one. It is the only version of the card that reaches someone who cannot see it.

File weight is the second. PNG is lossless, which suits flat color and sharp lettering; the price is weight. Measured on this page, the example card came to about 223 KB as a PNG and 37 KB as a JPEG at the starting quality. Browsers must be able to write PNG from a canvas, while other formats are optional and silently fall back to PNG when unsupported, so a careful tool checks what it actually produced. Reading the finished file’s header, where a PNG keeps its width and height, is a cheap way to confirm the size.

Orientation is the third. A camera may store a photograph sideways with a tag saying how to turn it; the tag has eight values, covering rotations and mirror images. A browser asked to honor the tag when decoding will show the picture upright. A tool that ignores it puts a sideways photograph on a card.

No tool on a web page can do the last and most important check. It cannot see how a particular program will draw the card, how long that program remembers an old picture, or whether it will read the tags at all. Those are facts about other people’s software. The honest method is to build a picture that tolerates every plausible crop, describe it accurately in the tags, and then share the link somewhere private and look.