Guide
Astro Open Graph Tags: Layouts and Static Metadata
How an Astro layout prints the Open Graph title, description, image, and page URL into static HTML, and how to check that live published page.
By Abid Ali, maintainer of OG Scope
Published

Astro Open Graph tags are ordinary HTML in the page head. Astro does not have a separate social settings screen, and the config file does not print them. A layout that every page uses is where the tags belong, with the title, description, and image passed in for that page. On a static build, that HTML is what a crawler receives.
Astro's configuration guide says the config file is only for information required to build the project. Common meta data is added in the head with the same meta elements you would write on a plain HTML page. The pattern the guide shows is a Head component imported by a layout, so one file holds the tags and each page supplies its own values. The site option in that file is for the sitemap and for canonical URLs. It does not, by itself, write og:title or og:image.
Where an Astro layout writes the tags
Astro's layouts guide describes a layout as a normal component that usually supplies the html, head, and body, plus a slot for the page. Layouts are often kept in src/layouts. That folder is a convention, not a requirement. If the component contains a page shell, the html element has to be the parent of everything else in the file.
The sample layout imports a BaseHead component and passes it a title prop. The same prop is what the page sets when it wraps its content in the layout. Title, description, and image can travel the same way. A head that prints them looks like this:
---
const { title, description, image } = Astro.props;
const pageUrl = new URL(Astro.url.pathname, Astro.site);
---
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:url" content={pageUrl} />
<meta property="og:image" content={image} />This static metadata is the HTML the build writes into the page. The page URL line follows the layouts guide, which builds an address with new URL and Astro.site. Astro.url.pathname is the path of the page being rendered. Astro.site is the origin from the site option. The official Markdown sample then takes only the pathname for a canonical link. For og:url, keep the full address, including https and the host. A path with no host is not an address a crawler on another site can use. The og:url guide is the longer note on that value.
Set site in astro.config to the https origin you publish, because that is the base the URL is built from. The configuration guide also shows base, for a site served from a subpath, and trailingSlash. The Open Graph URL should be the address visitors actually open after those choices, not a second shape of the same page.
The image in the configuration guide's example is an absolute https URL. Use that form in the image prop. A path that starts with a slash, or a file that exists only on your machine, does not give a social crawler a file it can fetch. The Open Graph image size section covers the pixel size and the file types. 1200 by 630 is the usual frame for that absolute URL.
Markdown pages
A Markdown file in src/pages can name its layout in frontmatter. Astro says that layout property is special for those files, and that the component receives the frontmatter as props. The layout reads frontmatter.title, and the other fields you add, and it renders the Markdown in a slot. A post can carry its share text like this:
---
layout: ../layouts/BlogPostLayout.astro
title: "Field notes"
description: "What changed this week, in two lines."
image: "https://example.com/images/field-notes-1200x630.jpg"
---The layouts guide also exposes url on those props, the path of the page. That is the value to pass into new URL with Astro.site when the page is Markdown rather than an .astro file passing Astro.url itself. frontmatter.url is the same path. The layout property is the only special frontmatter key Astro adds. title, description, and image are yours.
That layout key is not special for a content collection. Astro says so directly: when you query and render a collection, the layout property in a file's frontmatter is not applied for you. The page that renders the collection entry has to use a layout component and pass the title, description, and image from the entry. A collection that only stores the fields, with no layout printing them into the head, publishes a page with no Open Graph tags.
MDX can use the same layout frontmatter. If you import a layout component yourself instead, Astro does not pass the frontmatter automatically. You pass the props. The layouts guide also says that once any layout is used, the layout must include the slot, because Astro will not add it to the MDX page for you.
What usually breaks
One head component with the title written as a fixed string is the common miss. Every page then shares one card. The configuration guide's Head component receives a title prop for that reason. Thread the description and the image through the same props, from the page or from frontmatter, and do not leave the example strings from the docs in the published layout.
A missing site option is the next one. The URL built from Astro.site needs that origin. Without it, og:url is not the absolute https address the tag should hold. Set site to the origin you publish, then build again. A base path or a trailing slash that does not match the live URL will put a different address in the tag than the one you shared.
The image value is the third. The docs example uses a full https URL, including the built file name. A relative path can look fine when you open the site yourself and still fail when a crawler on another host requests it. Point og:image at the absolute URL of the file the published site actually serves.
Tags added in the browser are the fourth. A static Astro page already has the head in the HTML response. A client script that inserts the meta elements after load does not change that first response. The guide to JavaScript meta tags is the general case: share cards read the HTML that came back, not the page after scripts run. A Next.js app sets the same kind of tags through its own metadata, covered in the Next.js Open Graph guide.
Check the published page
Build and deploy, then open the public URL and view the source. Search for og:title, og:description, og:url, and og:image. The title should be that page's title, the URL should be that page's https address, and the image should be an absolute URL. Then paste the same address into the Open Graph checker. It fetches the public HTML and shows an estimated card. The estimate is not a screenshot of Facebook, LinkedIn, or X.
Check a second page that uses the same layout. If both pages show the same title and the same image, the props are not arriving. Check one Markdown URL and one collection URL if the site has both, because the layout property does not cross from src/pages into a collection query. The dev server is a useful preview of the template. The published response is the one a share uses.
Check the live URL
Paste the page into the Open Graph checker to see the tags the server sends.
Open the Open Graph checker

