Mastodon Link Previews

JSON-LD, OpenGraph, and Meta Tags

Mastodon tries to give people nice link previews for any URLs shared in posts. It generally does so by looking for metadata on the linked page in a specific order:

  1. JSON-LD
  2. OpenGraph (OG)
  3. Standard Meta Tags

When a page has data in these formats, Mastodon pulls the information it needs to display a title, description, image, and more.

What is JSON-LD?

JSON-LD is a way to embed structured data in a page using JavaScript Object Notation (JSON). It’s often used for things like Schema.org data or rich snippets. Mastodon scans for it first.

JSON-LD-logo-64

Simple JSON-LD example:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "NewsArticle",
  "headline": "Sample Headline",
  "description": "A short summary of this news article.",
  "datePublished": "2025-02-22",
  "publisher_name": "Sample Publisher",
  "author_name": "John Doe",
  "author_url": "https://example.com/john-doe",
  "language": "en",
  "publisher_icon": "https://example.com/publisher-icon.png"
}
</script>

If this is present, Mastodon tries to build your preview from it.

OpenGraph Tags

Next, Mastodon checks for OpenGraph tags. It looks for:

  • og:type == ‘article’
  • og:title
  • og:description
  • article:published_time
  • og:image
  • og:image:alt
  • og:url
  • og:site_name
  • og:site
  • og:author || og.author:username
  • fediverse:creator
  • og:locale
  • twitter:player
  • twitter:player:stream
  • twitter:player:width
  • twitter:player:height

Example snippet:

<!-- Basic OG Article Tag -->
<meta property="og:type" content="article">

<!-- Core Data -->
<meta property="og:title" content="Example Article Title">
<meta property="og:description" content="A concise summary of the article.">
<meta property="article:published_time" content="2025-02-22T10:00:00Z">
<meta property="og:url" content="https://example.com/article.html">

<!-- Images -->
<meta property="og:image" content="https://example.com/article-image.jpg">
<meta property="og:image:alt" content="Descriptive alt text for the article image">

<!-- Site and Author -->
<meta property="og:site_name" content="Example News">
<meta property="og:site" content="Example News Site">
<meta property="og:author" content="Author Name">
<meta property="fediverse:creator" content="@author@mastodon.example">

<!-- Locale -->
<meta property="og:locale" content="en_US">

<!-- Twitter Player Tags (for embedded media) -->
<meta property="twitter:player" content="https://example.com/player.html">
<meta property="twitter:player:width" content="640">
<meta property="twitter:player:height" content="360">
<meta property="twitter:player:stream" content="https://example.com/media/stream.mp4">

Standard Meta Tags

Mastodon tries the standard HTML meta tag description if a description isn’t already set using one of the above methods.

Example snippet:

<meta name="description" content="Summary for older platforms and basic crawlers">

Putting It All Together

If you want Mastodon to reliably create a preview:

  1. Include well-formed JSON-LD or OpenGraph tags in your HTML.
  2. Supply a descriptive title, description, and relevant media.
  3. Provide an og:url that matches your page URL.

Meanwhile, you can still add a standard meta description or Twitter card tags to cover other platforms.

References

That’s it. Use JSON-LD first if possible, or rely on OpenGraph for more direct control, and add standard meta tags for broad coverage.

In addition to those meta properties, it’s helpful to define link tags for canonical URLs and icons and Mastodon will also take advantage of these:

<!-- Canonical Link (helps search engines identify the main version of the page) -->
<link rel="canonical" href="https://example.com/article.html">

<!-- Apple Touch Icon (used when users save your page to an iOS home screen) -->
<link rel="apple-touch-icon" href="https://example.com/apple-touch-icon.png" sizes="180x180">

<!-- Favicon or generic site icon -->
<link rel="icon" type="image/png" sizes="32x32" href="https://example.com/favicon-32x32.png">