OpenGraph, Twitter Cards, and article metadata in Astro

SeriesPart of How this blog was built — documenting every decision that shaped this site.

When someone shares a link to a blog post, the card that appears in Slack, LinkedIn, or iMessage is determined by OpenGraph tags in the <head>. Get them wrong and the shared link is an unformatted URL. Get them right and it shows the post title, description, and a properly sized cover image.

This is table stakes for any public-facing blog, but the implementation details matter — specifically, how to handle different content types (articles vs. pages), where to put canonical URLs, and how to avoid the common mistake of sharing a relative image path that produces a broken card.

Centralising metadata in BaseLayout

All meta tags are defined once in BaseLayout.astro. Every page passes what it needs as props; the layout handles the markup. This avoids duplication and ensures no page accidentally skips essential tags:

1
interface Props {
2
  pageTitle: string;
3
  description?: string;
4
  ogImage?: string;
5
  ogType?: "website" | "article";
6
  canonicalUrl?: string;
7
  pubDate?: Date;
8
  author?: string;
9
  tags?: string[];
10
}
11

12
const {
13
  pageTitle,
14
  description = "Practical software engineering guidance from Roger Rajaratnam for people breaking into tech, engineers growing in confidence, and teams improving engineering practice.",
15
  ogImage = "/og-image.png",
16
  ogType = "website",
17
  canonicalUrl = Astro.url.href,
18
  pubDate,
19
  author,
20
  tags,
21
} = Astro.props;

The default description covers general pages. The default ogType is "website". Both are overridden for posts. The default canonicalUrl is Astro.url.href — the fully qualified URL including the site’s site value from astro.config.mjs.

The OpenGraph block

1
<!-- OpenGraph -->
2
<meta property="og:type"        content={ogType} />
3
<meta property="og:site_name"   content={siteName} />
4
<meta property="og:title"       content={pageTitle} />
5
<meta property="og:description" content={description} />
6
<meta property="og:url"         content={canonicalUrl} />
7
<meta property="og:image"       content={new URL(ogImage, Astro.site ?? Astro.url.origin).href} />
8
<meta property="og:image:width"  content="1200" />
9
<meta property="og:image:height" content="630" />
10
<meta property="og:locale"      content="en_GB" />

The og:image value deserves attention. A relative path like /og-image.png won’t work in OG tags — social crawlers need an absolute URL. Constructing it with new URL(ogImage, Astro.site) handles both cases: if ogImage is already absolute it passes through unchanged; if it’s a root-relative path it’s resolved against the site’s configured base URL.

siteName is a plain constant — const siteName = "Sourcier" — defined at the top of BaseLayout.astro. og:locale uses the IETF language tag for British English, which matches the site’s target audience.

1200×630 is the recommended OG image size that renders well across Facebook, LinkedIn, and Slack.

Article-specific tags

When ogType is "article", the Open Graph protocol defines additional properties for structured article metadata. These are conditionally rendered:

1
{pubDate && (
2
  <meta
3
    property="article:published_time"
4
    content={pubDate.toISOString()}
5
  />
6
)}
7
{author && <meta property="article:author" content={author} />}
8
{tags && tags.map((tag) => (
9
  <meta property="article:tag" content={tag} />
10
))}

article:published_time uses the ISO 8601 format with timezone — Date.toISOString() provides this. article:tag can appear multiple times, once per tag. Some scrapers and indexers use these to understand content type and category.

Twitter Cards

X (formerly Twitter) has its own metadata system that runs parallel to OpenGraph. The summary_large_image card type displays the image at full width above the title and description:

1
<meta name="twitter:card"        content="summary_large_image" />
2
<meta name="twitter:title"       content={pageTitle} />
3
<meta name="twitter:description" content={description} />
4
<meta name="twitter:image"       content={new URL(ogImage, Astro.site ?? Astro.url.origin).href} />

The property names keep the twitter: prefix — these are a stable protocol standard and won’t change regardless of the platform rebrand. X falls back to OpenGraph values for some properties, but it’s more reliable to specify them explicitly. The image URL construction is the same as for OG.

Canonical URLs

1
<link rel="canonical" href={canonicalUrl} />

The canonical tag tells search engines which URL is the authoritative version of a page, which matters if content appears at multiple URLs or is syndicated elsewhere. canonicalUrl defaults to Astro.url.href so it’s correct without any manual input, but can be overridden for pages that need a different canonical (for example, a paginated page that canonicalises to page 1).

Passing metadata from post pages

MarkdownPostLayout.astro extracts the relevant frontmatter fields and passes them to BaseLayout:

1
const ogImage = frontmatter.cover?.image?.src ?? undefined;
2

3
<BaseLayout
4
  pageTitle={`${frontmatter.title} — Sourcier`}
5
  description={frontmatter.description}
6
  ogImage={ogImage}
7
  ogType="article"
8
  pubDate={frontmatter.pubDate}
9
  author={frontmatter.author}
10
  tags={frontmatter.tags}
11
>

The ogImage falls back to undefined if no cover is present, which means BaseLayout will use the default /og-image.png for posts without cover images.

You can browse the rest of the site code in the web-sourcier.uk repository.

OpenGraph, Twitter Cards, and article metadata in Astro

Centralising metadata in BaseLayout

The OpenGraph block

Article-specific tags

Twitter Cards

Canonical URLs

Passing metadata from post pages

Need help raising the bar?

Comments

Leave a comment

Get practical engineering notes