Creating Twitter Cards

Thu, Jun 25, 2020

Twitter Cards provide a way of automatically displaying an image and summary information about a web page when a URL is posted in twitter. By setting the appropriate metadata within a page’s header, we can have links to our blog display attractive images and link summaries when someone tweets a link to our site. This article will explain what Twitter Cards are and how to configure Hugo to generate the necessary metadata to create these cards.

About Twitter Cards

Twitter Cards are simple summaries of web links that automatically appear in tweets without requiring any effort by the person tweeting the link. These cards are generated by Twitter by examining metadata information contained within the <head> section of the HTML document referenced by the tweeted link. When this metadata is present, Twitter will automatically generate a card, similar to the image below:

In this example, only the text prior to the image is typed by the tweet author. When posting, Twitter will generate the rest and append to the tweet.

Twitter Card Metadata

As mentioned above, Twitter Cards are generated when certain <meta> properties are defined within the <HEAD> section of the HTML file. The following properties, at minimum, are required to generate at Twitter Card:

Name	Description
`twitter:card`	Type of card desired. (see below)
`twitter:title`	A concise title for the content, will be displayed as a bold heading in the Twitter Card.

In addition, the following properties are optional:

Name	Description
`twitter:description`	Summary text to be displayed in the Twitter Card (web client only)
`twitter:image`	Image to be displayed in the card
`twitter:image:alt`	Text description of image for accessibility
`twitter:site`	Twitter username to associate with the card
`twitter:player`	HTTPS URL for iFrame audio/video player (Player Card only)
`twitter:app:*`	Various properties for App Store or Google Play Store integration (App Card only)

Further details can be found in the Twitter Card documentation, specifically the markup code reference.

Types of Twitter Cards

In order to accommodate different use cases, Twitter has defined the following four types of Twitter Card:

Summary Cards

Summary Cards are suited for general web page content such as blog posts. A Summary Card displays a small, square thumbnail to the left of the content. This makes it ideal for icons and simple branding.

Summary With Large Image Cards

Summary with Large Image Cards, as the name implies, is similar to the Summary Card but displays a larger image, typically above the card title and description. As one can see from the example below, the larger image is well suited for grabbing the attention of viewers within a busy Twitter timeline. The larger size of the rendered image also allows for more elaborate (and attention grabbing) images than the smaller Summary Card thumbnails.

Example of Summary with Large Image Twitter Card

Player Cards

Player Cards are intended for direct linking to audio or video clips. The clip is accessed via the URL specified in the twitter:player metadata header. Examples of configuring a Player Card can be found in Twitter’s GitHub repo.

App Cards

App Cards are specialized cards meant to link to applications with the Apple App Store or the Google Play Store. Developers can define names, IDs and URLs for iphone, ipad and googleplay platforms with the page heading using metadata tags such as twitter:app:name:iphone. Additional information can be found in the App Card Developer Overview

The remainder of this doc will focus only on Summary and Summary with Large Image Twitter Cards as these are the most relevant to my use cases (linking to blog posts) and are the types I have implemented and tested myself.

Image Restrictions

The two Summary card types have distinct and sometimes incompatible requirements for the image they will display. The restrictions for each can be summarized as follows:

Attribute	Summary	Summary with Large Image
Aspect Ratio (W:H)	1:1	2:1
Min Size (W x H)	144 x 144	300 x 157
Max Size (W x H)	4096 x 4096	4096 x 4096
Max File Size	5 MB	5 MB

As far as supported image formats, Twitter Cards support JPG, PNG, WEBP and GIF (note: only the first frame will be displayed for animated GIFs).

Generating Metadata with Hugo

Hugo has built in support for generating Twitter Card via an internal template. To enable this template, simply copy the following to the desired web page layout between the <head> and <\head> tags:

{{ template "_internal/twitter_cards.html" . }}

You can look at the hugo source code in the file, tpl/tplimpl/embedded/templates/twitter_cards.html, to see how Hugo generates the metadata entries for Twitter. In summary:

Hugo tries to use the first image in .Params.images (ie. images defined in the page’s front matter) for twitter:image, if present
otherwise, Hugo looks for images associated with the page (ie. within the same page bundle) whose names match either *feature*, *cover* or *thumbnail*.
finally, if still unsuccessful, Hugo will attempt to use the first image in .Site.Params.images (read from the site config file)
If no image is found, Hugo sets twitter:card to “summary” rather than “summary_large_image”.
Next, Hugo attempts to fill the twitter:description field from either the .Description page variable, the autogenerated.Summary page variable (see https://gohugo.io/content-management/summaries/) or the .Site.Params.description field from the global site config file.
Finally, Hugo sets twitter:title, twitter:site and twitter:creator to the values of .Title, .Site.Social.twitter and any .twitter fields in .Site.Authors, respectively.

Customizing Hugo Integration

While the built-in support for Twitter Cards in Hugo is laudable, the beauty of Hugo is being able to customize how a site is generated. If the built-in support does not satisfy your needs, it is quite easy to create your own template file to include within the HTML <HEAD> section. In my case, I was able to create a template to leverage the same front matter that I use to select the image at the top of each blog post.

Testing Twitter Cards

Once you have included an appropriate template to add the desired Twitter metadata fields to your page(s), it is useful to test the rendering of the Twitter Card for your new pages. While it is certainly possible to perform test tweets to verify whether a Twitter Card will be created correctly for a given page, Twitter provides a card validator that can be used to generate a sample card for a given URL. By entering the URL to be tested, the validator can check for the required fields and render a sample Twitter Card fo you to verify.

Of note, as Twitter needs to query the URL provided, the validator cannot work on test pages hugo server hosts locally unless the network or firewall is configured to allow external access to your test server. As I am hosting on Netlify, I am able to use their deploy previews feature to access live versions of my site based on GitHub pull-requests. Each pull-request (or modification to an existing pull request) will generate a new publicly accessible website located at a unique but obfuscated URL. This is a great way to perform final checks on a website before deploying to production.

Gotchas

In testing using images for Twitter Cards, I came across a few “gotchas” that prevented my cards from initially rendering as expected.

twitter:image must be an absolute URL. The internal template attempts to force this but depending on the BaseURL configuration, the resulting URL may not be correct. This is especially true for the aforementioned Netlify deploy previews. This thread on the Hugo discourse server gives some insight into proper settings to ensure production and deploy preview URLs are correct.
The image restrictions mentioned above are quite important. If you attempt to use an will prevent the image from being included if they are not met. Unfortunately, the Twitter Card validator does not provide informative error messages in this case, it simply does not display any image at all.

References

The following links were useful in writing this post:

Using Go Vanity URLs with Hugo

Remote Time Machine for Multiple Macs