How to Add Open Graph Images to a Hugo Static Site

To add an Open Graph image to a Hugo site, include Hugo’s embedded Open Graph partial in the active page head template, then set the page’s images front matter field. Build the site and inspect the generated HTML to confirm that the intended image URL appears in an og:image tag.

Hugo can also choose a page image automatically or use a site-wide fallback. For predictable page-specific previews, set images explicitly and make sure the image is available as a page or global resource.

1. Add Hugo’s Open Graph partial to the head

First inspect your theme and project templates to see which template produces the document’s <head>. If the active head template does not already include Open Graph metadata, add Hugo’s embedded partial call inside the head:

{{ partial "opengraph.html" . }}

For example, if your project uses layouts/_partials/head.html, place the call there alongside the rest of the head metadata. The precise head template path depends on the theme and project. Avoid adding a second copy if the theme already invokes the partial, or you may produce duplicate tags.

Hugo documents that you can override its embedded Open Graph partial by copying its source into layouts/_partials/opengraph.html and calling that partial from your template. Use an override only when the built-in behavior does not meet your requirements. Hugo’s embedded Open Graph template documentation describes the partial and its output.

2. Set the image for a page

Add an images array to the page’s front matter. For a page bundle, keep the image alongside the page content and use its filename:

---
title: A post title
images:
  - post-cover.png
---

If the content is not a page bundle, put the file where Hugo can resolve it as a global resource and use the correct resource path. You can also provide an external image URL:

---
title: A post title
images:
  - https://example.com/images/post-cover.png
---

Hugo resolves internal image paths against page resources and then global resources. When it finds a resource, it emits that resource’s permalink. An unresolved internal path is converted to an absolute URL, so check the built result carefully: a typo can become a plausible-looking URL even though the image was not included in the site output. External URLs are emitted as supplied.

Put the primary image first if you list more than one. Hugo’s embedded template can emit up to six og:image tags, and the Open Graph Protocol says the first value takes precedence when a property appears more than once. See the Open Graph Protocol.

3. Configure a site-wide fallback

Use params.images in your Hugo site configuration for a default image when a page has no explicit image and Hugo does not find a matching page resource. Hugo uses the first configured image as the fallback.

params:
  images:
    - images/default-social.png

Configuration file format and location depend on your project. The example shows YAML configuration; use the equivalent structure if your site uses TOML or JSON. A page-level images value gives you control over that page’s preview, while params.images supplies a site-wide default.

4. Understand Hugo’s image selection order

The embedded partial selects images using this documented order:

1. If page front matter contains images, Hugo processes those values. Internal paths are resolved against page resources and then global resources; external URLs are used as given.
2. Otherwise, Hugo searches page resources for a filename matching *feature*.
3. If none matches, it searches for *cover*, then *thumbnail*.
4. If no qualifying page resource is found, it uses the first entry in site configuration params.images, if configured.

For a specific page, the Open Graph image for a specific page should be set in that page’s images front matter. Do not assume a custom field such as featured_image is read by Hugo’s embedded partial. A theme can implement its own field conventions, so check the active template before relying on one.

Choice	Scope	When to use it
Page images front matter	One page	Use when a page needs a deliberate preview image.
Page resource filename matching	One page	Use Hugo’s automatic fallback when the page bundle contains a suitable feature, cover, or thumbnail image.
params.images	Site-wide fallback	Use a default when a page has no selected or matching image.
Override the embedded partial	Custom behavior	Use when you need to change how metadata or image selection is generated.

5. Check the Open Graph metadata Hugo generates

Build the site with your usual Hugo command, then inspect the generated HTML for a representative page. Check the source HTML rather than relying only on how a browser renders the page.

hugo
rg -n 'property="og:(title|type|image|url)"|property="og:image:alt"' public/

Confirm that the page head has the expected values:

• og:title: the page title, with site-title fallbacks.
• og:type: article for pages and website for list and home pages.
• og:image: the final absolute image URL you intended to publish.
• og:url: the page permalink, which serves as its canonical graph URL.

Hugo’s embedded template also documents og:site_name, og:description, and og:locale. For article pages it can emit section, publication and modification times, and up to six tags. The Open Graph Protocol identifies title, type, image, and URL as the four basic properties. It also describes optional image metadata such as MIME type, width, height, secure URL, and alt text; when a page specifies og:image, the protocol recommends specifying og:image:alt as well. Verify whether your active template emits the optional image properties you need.

6. Image files, processing, and build performance

Hugo can process images that are page resources, global resources, or remote resources. Processed results are cached. Build time and memory use can increase with source image dimensions, so scale down oversized source files before the build when practical. This is a build-performance consideration; the reviewed Hugo and Open Graph documentation does not establish one universally required image width, aspect ratio, or file size.

If you are targeting a particular social platform, check that platform’s current publishing guidance for its preferred preview dimensions and test the final public URL with its current preview tools. The Open Graph Protocol itself does not define one image size that works as a universal requirement across platforms.

7. Troubleshooting

Symptom	Likely cause	What to check
No og:image in the output	The active theme head does not call the embedded partial, or the theme supplies different metadata.	Inspect generated HTML and the theme’s head template. Add {{ partial "opengraph.html" . }} to the active head if needed.
The wrong image appears	Front matter is missing or misspelled, the path is wrong, or an automatic resource match or global fallback was selected.	Check the page’s images value and resource location. If relying on automatic selection, check the feature, cover, and thumbnail filename order and params.images.
The generated URL looks right but the image is absent	An unresolved internal path was converted to an absolute URL, or the resource was not published where expected.	Verify the actual file is included in the build and that the final image URL serves that image.
The page title, type, or URL is unexpected	Page metadata, site configuration, permalink settings, or a theme override affects the generated values.	Inspect the full head and compare it with the page front matter, site settings, and active partial.
A social platform shows an old or missing preview	The generated HTML may be correct while the platform’s crawler or cache has not refreshed.	Verify the public page and image URLs, then use that platform’s current preview or debugging tool. Crawler and cache behavior is platform-specific.

When duplicate Open Graph tags appear, check whether both the theme and your project call a partial that emits them. Keep one authoritative set of tags, and put the intended image first if multiple image tags are deliberately emitted.

8. Capture the page to check its rendered appearance

Open Graph metadata is HTML head data, so a screenshot does not replace checking the generated tags. A screenshot can still help you review the page’s rendered design and confirm that the source image looks right in context.

Or skip the browser setup

To capture a rendered page without setting up a browser automation stack, send a GET request to ScreenshotNeo. Set url to the public page you want to inspect and replace the placeholder API key. See the ScreenshotNeo API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/blog/post/ -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com/blog/post/"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com/blog/post/'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides screenshot, page information, and PDF tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Learn about ScreenshotNeo or sign up for 1,000 free screenshots a month with no card.

FAQ

Can I use more than one Open Graph image?

Hugo’s embedded partial can emit up to six image tags. Put the preferred image first because the protocol gives the first value precedence when a property is repeated.

Does Hugo read featured_image automatically?

Hugo’s documented embedded partial uses the page images parameter and its documented resource filename fallbacks. A theme may implement additional conventions, so inspect its templates.

Does setting Open Graph metadata change what appears on the page?

No. These tags describe the page in its HTML head for graph and sharing metadata; they do not by themselves render an image in the visible page body.