To add Open Graph images to a Hugo site, make sure your head template calls Hugo’s embedded opengraph.html partial, then set the page’s images front matter field. Build the site and inspect the generated HTML head to confirm the intended og:image URL is present.
Add the Open Graph partial to your Hugo head
- Inspect the active theme’s head template and check whether it already calls Hugo’s embedded Open Graph partial. Avoid adding a second call if the theme already outputs the tags.
- If it is missing, add
{{ partial "opengraph.html" . }}to the head template used by your pages. - Build the site and inspect the generated page source to confirm the metadata appears inside the document’s
<head>.
If you need behavior different from Hugo’s embedded template, Hugo documents copying its source into layouts/_partials/opengraph.html and calling that custom partial from the template. See Hugo’s embedded templates documentation.
Set an Open Graph image for a specific page
Use the images front matter parameter. For example, put the image in a page bundle alongside the page’s index.md and use its filename:
---
title: A post title
images:
- post-cover.png
---
Hugo resolves an internal path against that page’s resources and then global resources. If it finds a matching resource, it uses the resource permalink. If it cannot find the internal path, Hugo converts the path to an absolute URL; an external URL is used as supplied. Check filename spelling and capitalization against the actual file, and make sure the image is included in the page bundle or global resources as intended.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
For the predictable page-specific result, set images explicitly. Hugo’s built-in partial reads this field; a theme may support other conventions, but do not assume a custom field such as featured_image controls the built-in partial.
Choose a site-wide fallback
When a page has no explicit image and no qualifying page resource, configure params.images in your Hugo site configuration. Hugo uses the first configured image as the site-wide fallback.
The built-in selection order is:
- Use each value in page-level
images, if set. - Otherwise, search page resources for a filename containing
feature, thencover, thenthumbnail. - If none is found, use the first entry in
params.images, if configured.
The embedded template can emit up to six og:image tags. Put the preferred image first: under the Open Graph Protocol, the first value takes precedence when the same property appears more than once.
Rank #2
Check the metadata Hugo generates
Inspect the built page’s HTML source, not only its rendered appearance. Confirm the head contains the intended image URL and the metadata matches the page:
og:title: page title, then site title, thenparams.title.og:type:articlefor pages andwebsitefor list and home pages.og:image: the selected image URL or URLs.og:url: the page permalink.og:site_name: site title, falling back toparams.title.og:description: page description, page summary, thenparams.description.og:locale: pagelocale, then the site language locale, with hyphens changed to underscores.
For article pages, the embedded template also documents article section, publication and modification times, and up to six tags. The protocol’s four basic properties are og:title, og:type, og:image, and og:url. It also defines optional image properties for a secure URL, MIME type, width, height, and alt description; when a page specifies og:image, the protocol says it should also specify og:image:alt. Check what your active theme actually emits if you require those optional fields.
Choose where the image comes from
| Choice | Best for | How Hugo uses it |
|---|---|---|
| Page bundle resource | A page-specific preview image | Set its path in the page’s images field; Hugo resolves it as a page resource. |
| Global resource | An image shared across pages or a fallback | Hugo can resolve an internal path against global resources; params.images supplies the site-wide fallback. |
| External URL | An image hosted elsewhere | Use the external URL in images; Hugo emits it as supplied. |
| Custom partial | Selection or metadata behavior the embedded partial does not provide | Copy the embedded source to layouts/_partials/opengraph.html and call the custom partial. |
Image dimensions and build performance
The reviewed Hugo and Open Graph documentation does not establish one universally required image width, aspect ratio, or file size. Check current publishing guidance for the specific social platform you target rather than treating one dimension as an Open Graph requirement.
Hugo can process page, global, and remote image resources, and its documentation says processed results are cached. Larger source dimensions require more build time and memory; if an image is much larger than its published use requires, scaling it down before the build can reduce that work. This is a build-performance consideration, not a universal social-preview size rule.
Troubleshooting missing or incorrect previews
No og:image appears in the page source
- Verify the active theme’s head template calls
{{ partial "opengraph.html" . }}, or confirm the theme supplies equivalent metadata. - Check the generated HTML source and make sure the tags are inside the document head.
The wrong image appears
- Check the page’s
imagesfront matter path, including spelling and capitalization, and confirm the file is available as a page or global resource. - If the page has no explicit image, check for page-resource names containing
feature,cover, orthumbnailin that precedence order, then inspect the firstparams.imagesentry. - Inspect the final image URL in the generated HTML. If multiple image tags are present, put the preferred image first.
The page image is right, but the preview is stale or absent on one platform
Platform crawler and cache behavior is not specified by Hugo’s documentation or the Open Graph Protocol. Confirm that the page exposes the intended image URL and canonical og:url, then use the relevant platform’s current preview or debugging tool to check its cached result.
Or skip the browser setup
If you need a rendered screenshot rather than an Open Graph tag, ScreenshotNeo can return a website screenshot with one GET request. The example saves a screenshot of the published page as WebP; see the ScreenshotNeo API documentation for parameters and response details.
Rank #4
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/post/ -o shot.webpScreenshotNeo accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and each response includes X-Page-Verdict and X-Billed headers. Its MCP server provides take_screenshot, get_page_info, and capture_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 shots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does Hugo’s built-in Open Graph partial read `featured_image`?
No. Its documented page-level image field is `images`; a theme may implement a different convention.
Does Open Graph require one specific image size?
The reviewed Open Graph Protocol and Hugo documentation do not specify one universal width, aspect ratio, or file size. Check guidance for the particular platform you target.
Free tools Windows power users keep installed
One-click scans. No signup required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
