Back to Docs

Documentation framework

Starlight OG Image Integration

Add automatic per-page Open Graph images to Starlight documentation with native route middleware and MyOG.social.

Prerequisites

  • Starlight 0.33 or newer, with an Astro version supported by that Starlight release
  • A production site URL configured in astro.config.mjs and publicly accessible documentation
  • A MyOG account with the public domain added and available image credits from a paid plan or the 10-day card trial

How MyOG fits Starlight

Starlight builds the head for each documentation page. Its route middleware can add a MyOG image URL to that head before the HTML is rendered, without a plugin package or client-side script.

The recipe reads Starlight's final canonical link, including the base path, locale and trailing slash. MyOG generates the image when the image URL is requested; the Astro build only writes metadata.

The editable head API was added in Starlight 0.33. This recipe was build-tested with Starlight 0.33.0 on Astro 5.18.0 and Starlight 0.42.6 on Astro 7.2.10. Other releases need their own build check.

1

Choose a layout

MyOG detects page content and branding automatically. The layout only controls image composition.

2

Add the Starlight code

astro.config.mjs

Merge site and routeMiddleware into your existing configuration.

Preview anonymously. Sign in to get complete install code for your account.

Sign in to get install code

src/myogRouteData.ts

Add image tags after Starlight and other route middleware have built the head.

Preview anonymously. Sign in to get complete install code for your account.

Sign in to get install code

Starlight already supplies twitter:card. The handler adds only missing image tags; page image overrides stay in control.

3

Place it correctly

  1. Set Astro's site to your public HTTPS origin. Keep your existing Starlight options and add routeMiddleware pointing to src/myogRouteData.ts.
  2. If routeMiddleware is already configured, add this file to the existing array. The handler waits for later middleware before reading the final head.
  3. Create src/myogRouteData.ts with the account-specific code below. Keep the account hint from your MyOG account; it identifies the installation and is not an API secret.
  4. Remove a global fallback og:image if you want MyOG on pages without a page-specific image. Remove that fallback's old image dimensions and alt text too.
  5. Build the site and inspect the generated HTML before publishing.

Avoid duplicate og:image tags

Starlight merges configured head tags with page frontmatter before this handler runs. The handler leaves any existing og:image untouched, including page overrides and global fallback images. When it adds MyOG, it preserves an existing twitter:image and Starlight's twitter:card. Middleware additions are not deduplicated automatically, so keep only one copy of this handler and inspect tags added by other integrations.

Dynamic pages

The canonical link supplies each home, docs, nested and localized URL. The entire URL is encoded once as a query value, preserving encoded path segments and reserved characters. A custom canonical must point to a public page on a domain registered in MyOG.

Test the result

  • Run your Astro build. In the home page and a nested docs page, confirm one og:image and one twitter:image, with the expected page URL after decoding the MyOG url parameter once.
  • Check a base-path or localized page and the configured trailing-slash behavior. The MyOG target should match the canonical link.
  • Give one page a frontmatter og:image and twitter:image. Confirm both overrides survive the build and unrelated title, description and canonical tags remain intact.
  • Confirm the 404 page has no generated MyOG tags. With site unset or the account hint empty, the middleware should add nothing.

Start with the MyOG Open Graph Checker, then refresh social platform caches if needed.

Known limitations

This recipe covers pages rendered by Starlight. Separate Astro pages need their own head setup, described in the Astro guide.
An existing global og:image prevents automatic images until you remove it. A custom Head component must render starlightRoute.head for the middleware to take effect.
Private documentation cannot be fetched by MyOG or public social crawlers. Account signup and the free metadata checker do not activate paid image serving; keep the domain registered and image credits available.

Sources

Ready to get started?

Create a MyOG account, add your docs domain, then start the card trial to serve images.

Already have an account?

234557e8ea386a5b040a564592ebfc437920d0fb