Article Body Blocks

Aside Block

Use for supplemental information apart from the main text. They’ll usually appear to the left/right on large screens and appear inline on smaller screens, so these should be used with content that’s not overly long.

Markdown and HTML are both supported.

For examples of basic asides, asides with custom styles, and other alternatives, see this guide.

Image Block

Using Images with transparency

In order for images to look best in light/dark mode, there are a couple situations for when you might want transparent backgrounds:

• A single graphic with a transparent background and text colors that have enough contrast on both light and dark page backgrounds
• Compositions of multiple photos
• Photos with page tears or other types of edge treatments

The recommended approach to handling this in our CMS is to save the image in two formats:

Targeted to the web platform in Craft: .webp which supports transparency and generates small file sizes for for both graphics and photos (unlike .png). The latest versions of Photoshop support webp out of the box (File > Save As… > Change the file format to WebP in the dropdown).

Targeted to all other platforms in Craft: .jpeg or .png, whichever results in a smaller file size. Do not use png for anything other than a graphic or there will be problems. (If you’re saving this image as a jpeg, build in a white background in a way that looks intentional when viewed in dark mode:

• For photo compositions, for example, add a white border on all sides of an image.
• For images with page tears, for example, use an image that does not have the edge treatment.

If you are not able to create two images (due to time crunch, or if you aren’t able to make a webp image), then upload a single jpeg or png image for all platforms. Again, do not use png for anything other than a graphic or there will be problems.

Video (Self-Hosted) Block

For embedding mp4 video files directly. There are two options for video behavior: “Regular” videos display player controls and do not autoplay. “Looping Cinemagraphs” autoplay, do not display player controls and are muted.

Regardless of the behavior, self-hosting should only be used short videos (anything under a minute) as this has an impact on our server hosting costs as well as Google’s measurement of our page size. Use a third-party platform like Youtube to host anything longer.

E.g. consider: 50,000 page views on an article with a 20mb video = 1 terabyte of bandwidth!

Cinemagraphs

For cinemagraphs, see the Cinemagraphs production guide for more info.

Regular (Click-to-play)

For regular videos, most of the information in the Cinemagraphs production guide above apply. File size requirements are slightly more lenient, but should not exceed 20mb in total.

Video (Third-Party) Block

For embedding YouTube and Vimeo videos. Unlike the third-party videos of old, though, the embed code is not needed. Just copy the video ID out of the URL. On YouTube, it’s the part that comes after “watch?v=”; on Vimeo, it’s the part that comes after “vimeo.com/”.

In general, hosting on Youtube is preferred over Vimeo (due to the next section).

Vimeo

There is an additional consideration for Unlisted videos hosted on Vimeo: a “security hash” is required in order for the embed to work.

This is found in the URL, in the query string (the part after the ‘?’), following “h=” and before any ‘&’ (if there is one). For example:

https://player.vimeo.com/video/729688649?h=7ab455fbdb

7ab455fbdb is the security hash that you add into Craft.

Embed (Web-Only)

Use to include iframes/embeds from other third-party platforms (Instagram, TikTok, etc.) or to include custom interactives and graphics built with html/css/js.

Mobile Image: A separate mobile image can be provided, for situations where a different image reads better at smaller sizes (often handy for charts). It will appear on mobile web.

Off-Platform Support

Embed blocks will not appear off-platform. Fallback blocks are recommended.

Callout

For embedding callout forms. (Screendoor and Jotform embeds both work.)

Choose an existing Callout cms entry (we do this so it’s easy to reuse the same form across multiple articles) that meets the following conditions:

• It is a "Callout V3 Minimal" entry type.
• It has embed code in the “Callout Form” field.

If you use this block and don’t see any content in it when you preview/publish, make sure the 2 conditions above are met.

Callout Link

For linking out to Airtable forms. This is a short-term workaround due to Airtable forms not working for us.

Be sure to fill out the Title (Hed from the callout), Description (Dek from the callout), and the URL.

The button text is optional, leaving it empty will cause the button to show “Get in Touch”.